A JSON format to describe civic data resources & microservices

microcivic.json

{
	"name": "phl-property-tax-balances",
	"keywords": ["tax", "property", "delinquent", "deadbeat"],
	"license": "CC0",
	"sources": [{
		"name": "City of Philadelphia",
		"web": "http://opendataphilly.org",
		"email": "data@opendataphilly.org"
	}],
	"resources": [{
		"name": "Property tax balance API",
		"url": "https://data.phila.gov/resource/y5ti-svsu.json",
		"format": "json",
		"encoding": "UTF-8",
		"authentication": false,
		"ratelimit": true,
		"documentation": "https://www.opendataphilly.org/dataset/property-tax-balances/resource/927260a9-1e73-41c7-8553-9061d0334f47"
	}, {
		"name": "Property tax balance download",
		"path": "/realestate-tax-balance.csv",
		"format": "csv",
		"bytes": "",
		"hash": "sha1:8843d7f92416211de9ebb963ff4ce28125932878"
	}],
	"schema": {
		"fields": [{
				"name": "interest",
				"type": "number"
			},

			{
				"name": "lien_number",
				"type": "string"
			},

			{
				"name": "location",
				"type": "string"
			},

			{
				"name": "other",
				"type": "number"
			},

			{
				"name": "owner",
				"type": "string"
			},

			{
				"name": "parcel_number",
				"type": "string"
			},

			{
				"name": "penalty",
				"type": "number"
			},

			{
				"name": "principal",
				"type": "number"
			},

			{
				"name": "tax_period",
				"type": "number"
			},

			{
				"name": "total",
				"type": "number"
			}
		]
	}
}

Format mostly tries to follow data packages standard with the following exceptions:

• keywords: This is lifted directly from packackage.json format from npm. This would support discovery similar to npm search.
• authentication: Denotes whether microservice API requires authentication (e.g., a token) to use.
• ratelimit: Denotes whether the microservice is rate limited.
• documentation: A link to descriptive documentation for the API.

My feeling is that this format should live a level above the data packages standard, with the latter one of the standards that could be referred to. For example, something like schema would not appear here. Either this would refer to a standard that itself specifies where the scheme is to be found (data packages) or it just specifies a package file with that information.

Not sure exactly how to represent, but other things of interest would be:

• maturity: Some measure indicating adherence to quality standards
• validation: pointer to testing/validation resources
• use: pointer to or even just included usage resources (e.g., wrappers to get, display, test, etc.)