Requirements for smartAPI 'semantic type' extensions

[mbrush]

Following up on hackathon discussions about extending the smartAPI spec to capture the 'semantic type' of entities described by data. One thing I would like these extensions/refinements to support is derivation of a simple 'Translator API Catalog' that contains human-readable, summary-level descriptions of API content and accessibility (see #8).

An informal schema for this catalog is here, and describes the elements we would ideally like to extract or derive from the smartAPI files. About half of these elements map directly to existing smartAPI element/fields, so are already achievable (apiName, accessURL, description, license, termsOfService, accessRestrictions).

The semantic typing extensions would ideally support derivation of two additional elements in the catalog schema:

• entityTypes: array of terms describing the entity types that the data returned by the API is about
• entityAssociations: and array of hyphen-separated pairs of entities types describing associations that can be obtained form the API (and optionally a relationship type or entity role)

Other elements in the catalog schema that we would like to derive include:

• dataLevel
• primarySources

But if these are not suited for inclusion in the smartAPI spec, they could be implemented elsewhere - e.g. added under the "translator" element in the API_LIST.yml file, where other Translator-specific metadata currently lives.