smartAPI specific elements automatically generated from parent document
| Object | Field | Recommendation | Datatype | Description |
|---|---|---|---|---|
| OpenAPI Object | x-externalResources | External Resource Object | A list of external resources pertinent to the API. | |
| Info Object | description | SHOULD | string | See above. |
| Info Object | termsOfService | REQUIRED | URL | See above. |
| Info Object | version | REQUIRED | string | The version of the API definition. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) shall designate the feature set. Typically, .patch versions address errors in the API metadata, not the feature set. |
| Info Object | contacts | Contact Object | A list of other contacts. | |
| Info Object | x-accessRestriction | enum | Indicate whether there are restrictions to using the API. Values to use: none, limited, fee. | |
| Info Object | x-implementationLanguage | string | Language the API was written in. | |
| Contact Object | x-role | REQUIRED | enum | Indicate the role of the contact. Values can be: responsible organization,responsible developer,contributor,support. |
| Contact Object | x-id | SHOULD | string | A unique identifiers for the contact. |
| Server Object | x-location | string | Location, city and country of the server hosting the API. | |
| Server Object | x-maturity | enum | Maturity of the API. Values to use: development, staging, production. | |
| Operation Object | summary | REQUIRED | string | See above. |
| Operation Object | x-accessRestriction | enum | Access restrictions to invoke the operation. values: none, limited, fee. | |
| External Resource Object [smartAPI extension] | x-url | REQUIRED | string | . The URL for the target documentation. Value MUST be in the format of a URL. |
| External Resource Object [smartAPI extension] | x-type | REQUIRED | enum | values: api documentation, website,developer forum,mailing list,social media,publication |
| External Resource Object [smartAPI extension] | x-description | string | A short description of the target documentation. CommonMark syntax can be used for rich text representation. | |
| Parameter Object | x-parameterType | SHOULD | uri | A concept URI to describe the type of parameter. |
| Parameter Object | x-valueType | SHOULD | [uri] | A list of URIs to define the types of accepted value types. These should be selected from a registry of value types such as identifiers.org. This attribute is different from |
| Parameter Object | examples | Use the Schema object to define examples. | ||
| Response Object | content | SHOULD | Map[string, Media Type Object] | Use media type definitions listed at RFC6838. |
| Response Object | URI | Specify the json schema using a Reference Object, or use "x-uri" as an additional property in the schema field to point to an external location for an XML, RDF, etc schema. | ||
| Response Object | x-responseValueType | Response Value Type Object |Reference Object] | ||
| Response Value Type Object [smartAPI extension] | x-path | string | The path using dot notation to the element of interest. e.g. friend.name to follow the path from root object to the name attribute to the name field | |
| Response Value Type Object [smartAPI extension] | x-valueType | string | The value type for the field. e.g. http://identifiers.org/ncbigene indicates that the field type is from the NCBI Gene database | |
| Tag Object | x-id | URI | The name of the tag. Recommend that you use URI to specify the concept. |