Generic codelist schema?

[onthebreeze]

Some code lists are a simple list of code / name / description. But many code lists have some extra properties such as the rec 20 (units of measure) conversion, symbol, level/category, group etc. And some code lists are hierarchies (eg WTO harmonised tariff codes).

So, I'm wondering whether there is value in a generic schema/API spec that can be used for almost any code list. There's always complex exceptions that will need dedicated API specs but I'm thinking it would be a good outcome if, for every new code list, rather than design a custom API, we say "can we use the generic API spec or do we need a custom one?". And if 90% of the time the answer is "the generic one will do" then we save ourselves a lot of design effort and we also provide implementers with some consistent model.

Anyhow, I'm thinking of something like this:

Supports the idea of a versioned scheme, contained codes (optionally in a hierarchy) with core properties like status (raw, draft, stable, deprecated) and status date. The properties element allows for an arbitrary list of additional properties of a code as name/value pairs where the name is drawn from a standard taxonomy (JSON-LD reference file?).

Thoughts?

[onthebreeze]

I'll make a standard swagger spec for it. Also GET would allow filtering by any property name/value.

Not quite sure how best to handle hierarchies.

1. sub-resources? GET /tariffCodes/25/04/10 for code 2501410. Don't like this very much.
2. flatten all hierarchies and add a "level" attribute to the code? GET /tariffCodes?level=3 and include "parent" attribute in response. A GET at any level other than the lowest returns the contained collection.
3. some other approach?

some ideas from here https://www.foreign-trade.com/reference/hscode.htm

[kshychko]

@onthebreeze, here are my thoughts:
GET /tariffCodes/{code} returns the code itself no matter which level it is. It may include only the information about a number or a complete list of sub-codes. It can be made configurable or design choice. For example, GET /tarrifCode/{code}?includeSubCodes=true will return all the sub-codes details.
We can go without any additional parameters and only provide the information about sub-codes using another path, like GET /tariffCodes/{code}/subCodes. But we won't be going deeper, as it would add unnecessary complication.

Below some examples:

GET /tariffCodes/25 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
	"name": "25",
	"description": "SALT; SULPHUR; EARTHS, STONE; PLASTERING MATERIALS, LIME AND CEMENT",
	"numberOfSubCodes": 30
}

GET /tariffCodes/25/subCodes HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

[
	{
		"name": "2501",
		"description": "Salt (including table salt and denatured salt); pure sodium chloride whether or not in aqueous solution; sea water",
		"numberOfSubCodes": 1
	},
	{
		"name": "2504",
		"description": "Graphite; natural",
		"numberOfSubCodes": 2
	},
	{
		"name": "2530",
		"description": "Mineral substances not elsewhere specified or included",
		"numberOfSubCodes": 3
	}
]

GET /tariffCodes/2504?includeSubCodes=true HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
	"name": "2504",
	"description": "Graphite; natural",
	"numberOfSubCodes": 2,
	"subCodes": [
		{
			"name": "250410",
			"description": "Graphite; natural, in powder or in flakes",
			"numberOfSubCodes": 0
		},
		{
			"name": "250490",
			"description": "Graphite; natural, in other forms, excluding powder or flakes",
			"numberOfSubCodes": 0
		}

	]
}

GET /tariffCodes/2504/subCodes HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

[
	{
		"name": "250410",
		"description": "Graphite; natural, in powder or in flakes",
		"numberOfSubCodes": 0
	},
	{
		"name": "250490",
		"description": "Graphite; natural, in other forms, excluding powder or flakes",
		"numberOfSubCodes": 0
	}
]

GET /tariffCodes/2504010 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
	"name": "250410",
	"description": "Graphite; natural, in powder or in flakes",
	"numberOfSubCodes": 0
}

[cmsdroff]

@onthebreeze i agree and did some digging today, Code, Name Description should be fine, some of the national standards institutes actually ignore everything around these when verifying the lists are correct. So i think at this stage if its good for them then good for us also, i cant find anyone who uses all the other ‘properties’ but i think the ability to include them is useful as we will come up against this I’m sure at some point so an answer is always useful.

@kshychko good clear examples, i agree separating the code in the example wouldn’t make sense, search for whats provided rather than rely on the user to split, if the above was documented and clear in the API then this for me is easy for everyone to follow.

I’m thinking regards management if its a UN code list we could promote if the column headings are ‘code, ‘name’ or ‘description’ then the relevant data auto populates these fields, anything else could be a ‘property’ by default and this could be scripted maybe. Just a thought as know its a separate issue from ticket.