From cc2be62a9314f33c10e7dfe30af4f8e826b9bb6b Mon Sep 17 00:00:00 2001 From: "Jonathan Thorpe (Sony)" Date: Mon, 5 Feb 2024 17:07:18 +0000 Subject: [PATCH] Initial commit of RAML --- APIs/ConfigurationAPI.raml | 101 ++++++++++++++++++ APIs/schemas/NcDatatypeDescriptor.json | 37 +++++++ APIs/schemas/NcDatatypeDescriptorEnum.json | 23 ++++ .../NcDatatypeDescriptorPrimitive.json | 10 ++ APIs/schemas/NcDatatypeDescriptorStruct.json | 35 ++++++ APIs/schemas/NcDatatypeDescriptorTypeDef.json | 25 +++++ APIs/schemas/NcDatatypeType.json | 12 +++ APIs/schemas/NcDescriptor.json | 18 ++++ APIs/schemas/NcMethodResult.json | 15 +++ APIs/schemas/NcMethodResultPropertyValue.json | 27 +++++ APIs/schemas/NcMethodStatus.json | 26 +++++ APIs/schemas/NcName.json | 10 ++ APIs/schemas/NcParameterConstraints.json | 22 ++++ .../schemas/NcParameterConstraintsNumber.json | 51 +++++++++ .../schemas/NcParameterConstraintsString.json | 35 ++++++ APIs/schemas/NcString.json | 6 ++ APIs/schemas/base.json | 14 +++ APIs/schemas/properties-base.json | 10 ++ APIs/schemas/property.json | 15 +++ APIs/schemas/rolePath.json | 17 +++ APIs/schemas/rolePaths-base.json | 10 ++ examples/base-get-200.json | 3 + examples/properties-base-get-200.json | 8 ++ examples/property-descriptor-get-200.json | 57 ++++++++++ examples/property-get-200.json | 4 + examples/property-value-get-200.json | 1 + examples/rolePath-get-200.json | 6 ++ examples/rolePaths-base-get-200.json | 3 + 28 files changed, 601 insertions(+) create mode 100644 APIs/ConfigurationAPI.raml create mode 100644 APIs/schemas/NcDatatypeDescriptor.json create mode 100644 APIs/schemas/NcDatatypeDescriptorEnum.json create mode 100644 APIs/schemas/NcDatatypeDescriptorPrimitive.json create mode 100644 APIs/schemas/NcDatatypeDescriptorStruct.json create mode 100644 APIs/schemas/NcDatatypeDescriptorTypeDef.json create mode 100644 APIs/schemas/NcDatatypeType.json create mode 100644 APIs/schemas/NcDescriptor.json create mode 100644 APIs/schemas/NcMethodResult.json create mode 100644 APIs/schemas/NcMethodResultPropertyValue.json create mode 100644 APIs/schemas/NcMethodStatus.json create mode 100644 APIs/schemas/NcName.json create mode 100644 APIs/schemas/NcParameterConstraints.json create mode 100644 APIs/schemas/NcParameterConstraintsNumber.json create mode 100644 APIs/schemas/NcParameterConstraintsString.json create mode 100644 APIs/schemas/NcString.json create mode 100644 APIs/schemas/base.json create mode 100644 APIs/schemas/properties-base.json create mode 100644 APIs/schemas/property.json create mode 100644 APIs/schemas/rolePath.json create mode 100644 APIs/schemas/rolePaths-base.json create mode 100644 examples/base-get-200.json create mode 100644 examples/properties-base-get-200.json create mode 100644 examples/property-descriptor-get-200.json create mode 100644 examples/property-get-200.json create mode 100644 examples/property-value-get-200.json create mode 100644 examples/rolePath-get-200.json create mode 100644 examples/rolePaths-base-get-200.json diff --git a/APIs/ConfigurationAPI.raml b/APIs/ConfigurationAPI.raml new file mode 100644 index 0000000..05e78f4 --- /dev/null +++ b/APIs/ConfigurationAPI.raml @@ -0,0 +1,101 @@ +#%RAML 1.0 +title: NMOS Configuration API +baseUri: http://api.example.com/x-nmos/configuration/{version} +version: 1.0 + +uses: + assets: assets.lib.raml + +annotationTypes: + monitoringInterval: + type: integer +/: + displayName: Base + get: + description: List of paths available from this API + responses: + 200: + body: + example: !include ../examples/base-get-200.json + type: !include schemas/base.json +/rolePaths: + displayName: Role Paths + get: + responses: + 200: + body: + example: !include ../examples/rolePaths-base-get-200.json + type: !include schemas/rolePaths-base.json + description: List rolePaths + /{rolePath}: + uriParameters: + rolePath: + type: string + get: + description: Get attributes of the object specified by rolePath + responses: + 200: + body: + example: !include ../examples/rolePath-get-200.json + type: !include schemas/rolePath.json + /properties: + displayName: Properties + get: + description: Get properties of the object + responses: + 200: + body: + example: !include ../examples/properties-base-get-200.json + type: !include schemas/properties-base.json + /{propertyId}: + uriParameters: + propertyId: + type: string + get: + description: Get attributes of a property + responses: + 200: + body: + example: !include ../examples/property-get-200.json + type: !include schemas/property.json + /value: + displayName: Value of a property + get: + description: Get value of a property + responses: + 200: + body: + example: !include ../examples/property-value-get-200.json + type: !include schemas/NcMethodResultPropertyValue.json + put: + descriptions: Set value of a property + responses: + 200: + body: + example: !include ../examples/property-value-get-200.json + type: !include schemas/modify-property.json + /descriptor: + displayName: Descriptor of property + get: + description: Get descriptor of a property + responses: + 200: + body: + example: !include ../examples/properties-descriptor-get-200.json + type: !include schemas/NcDatatypeDescriptor.json + /methods: + displayName: Methods + get: + description: List Methods + /{methodId}: + uriParameters: + propertyId: + type: string + patch: + /members: + displayName: Members + get: + description: List Methods + /descriptor: + displayName: Members + get: diff --git a/APIs/schemas/NcDatatypeDescriptor.json b/APIs/schemas/NcDatatypeDescriptor.json new file mode 100644 index 0000000..3876683 --- /dev/null +++ b/APIs/schemas/NcDatatypeDescriptor.json @@ -0,0 +1,37 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDatatypeDescriptor", + "description": "Base datatype descriptor", + "allOf": [ + { + "$ref": "NcDescriptor.json" + } + ], + "type": "object", + "required": [ + "name", + "type", + "constraints" + ], + "properties": { + "name": { + "$ref": "NcName.json", + "description": "Datatype name" + }, + "type": { + "$ref": "NcDatatypeType.json", + "description": "Type: Primitive, Typedef, Struct, Enum" + }, + "constraints": { + "anyOf": [ + { + "$ref": "NcParameterConstraints.json" + }, + { + "type": "null" + } + ], + "description": "Optional constraints on top of the underlying data type" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcDatatypeDescriptorEnum.json b/APIs/schemas/NcDatatypeDescriptorEnum.json new file mode 100644 index 0000000..499e13d --- /dev/null +++ b/APIs/schemas/NcDatatypeDescriptorEnum.json @@ -0,0 +1,23 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDatatypeDescriptorEnum", + "description": "Enum datatype descriptor", + "allOf": [ + { + "$ref": "NcDatatypeDescriptor.json" + } + ], + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "NcEnumItemDescriptor.json" + }, + "description": "One item descriptor per enum option" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcDatatypeDescriptorPrimitive.json b/APIs/schemas/NcDatatypeDescriptorPrimitive.json new file mode 100644 index 0000000..e2e352e --- /dev/null +++ b/APIs/schemas/NcDatatypeDescriptorPrimitive.json @@ -0,0 +1,10 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDatatypeDescriptorPrimitive", + "description": "Primitive datatype descriptor", + "allOf": [ + { + "$ref": "NcDatatypeDescriptor.json" + } + ] +} \ No newline at end of file diff --git a/APIs/schemas/NcDatatypeDescriptorStruct.json b/APIs/schemas/NcDatatypeDescriptorStruct.json new file mode 100644 index 0000000..486b87e --- /dev/null +++ b/APIs/schemas/NcDatatypeDescriptorStruct.json @@ -0,0 +1,35 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDatatypeDescriptorStruct", + "description": "Struct datatype descriptor", + "allOf": [ + { + "$ref": "NcDatatypeDescriptor.json" + } + ], + "type": "object", + "required": [ + "fields", + "parentType" + ], + "properties": { + "fields": { + "type": "array", + "items": { + "$ref": "NcFieldDescriptor.json" + }, + "description": "One item descriptor per field of the struct" + }, + "parentType": { + "anyOf": [ + { + "$ref": "NcName.json" + }, + { + "type": "null" + } + ], + "description": "Name of the parent type if any or null if it has no parent" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcDatatypeDescriptorTypeDef.json b/APIs/schemas/NcDatatypeDescriptorTypeDef.json new file mode 100644 index 0000000..2f0d247 --- /dev/null +++ b/APIs/schemas/NcDatatypeDescriptorTypeDef.json @@ -0,0 +1,25 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDatatypeDescriptorTypeDef", + "description": "Type def datatype descriptor", + "allOf": [ + { + "$ref": "NcDatatypeDescriptor.json" + } + ], + "type": "object", + "required": [ + "parentType", + "isSequence" + ], + "properties": { + "parentType": { + "$ref": "NcName.json", + "description": "Original typedef datatype name" + }, + "isSequence": { + "type": "boolean", + "description": "TRUE iff type is a typedef sequence of another type" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcDatatypeType.json b/APIs/schemas/NcDatatypeType.json new file mode 100644 index 0000000..101b089 --- /dev/null +++ b/APIs/schemas/NcDatatypeType.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDatatypeType", + "description": "Datatype type", + "enum": [ + 0, + 1, + 2, + 3 + ], + "type": "integer" +} \ No newline at end of file diff --git a/APIs/schemas/NcDescriptor.json b/APIs/schemas/NcDescriptor.json new file mode 100644 index 0000000..1443749 --- /dev/null +++ b/APIs/schemas/NcDescriptor.json @@ -0,0 +1,18 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcDescriptor", + "description": "Base descriptor", + "type": "object", + "required": [ + "description" + ], + "properties": { + "description": { + "type": [ + "string", + "null" + ], + "description": "Optional user facing description" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcMethodResult.json b/APIs/schemas/NcMethodResult.json new file mode 100644 index 0000000..daeed14 --- /dev/null +++ b/APIs/schemas/NcMethodResult.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcMethodResult", + "description": "Base result of the invoked method", + "type": "object", + "required": [ + "status" + ], + "properties": { + "status": { + "$ref": "NcMethodStatus.json", + "description": "Status for the invoked method" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcMethodResultPropertyValue.json b/APIs/schemas/NcMethodResultPropertyValue.json new file mode 100644 index 0000000..6b3873b --- /dev/null +++ b/APIs/schemas/NcMethodResultPropertyValue.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcMethodResultPropertyValue", + "description": "Result when invoking the getter method associated with a property", + "allOf": [ + { + "$ref": "NcMethodResult.json" + } + ], + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": [ + "number", + "string", + "boolean", + "object", + "array", + "null" + ], + "description": "Getter method value for the associated property" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcMethodStatus.json b/APIs/schemas/NcMethodStatus.json new file mode 100644 index 0000000..8196708 --- /dev/null +++ b/APIs/schemas/NcMethodStatus.json @@ -0,0 +1,26 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcMethodStatus", + "description": "Method invokation status", + "enum": [ + 200, + 298, + 299, + 400, + 401, + 404, + 405, + 406, + 409, + 413, + 414, + 417, + 423, + 500, + 501, + 502, + 503, + 504 + ], + "type": "integer" +} \ No newline at end of file diff --git a/APIs/schemas/NcName.json b/APIs/schemas/NcName.json new file mode 100644 index 0000000..c32acbd --- /dev/null +++ b/APIs/schemas/NcName.json @@ -0,0 +1,10 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcName", + "description": "Programmatically significant name, alphanumerics + underscore, no spaces", + "allOf": [ + { + "$ref": "NcString.json" + } + ] +} \ No newline at end of file diff --git a/APIs/schemas/NcParameterConstraints.json b/APIs/schemas/NcParameterConstraints.json new file mode 100644 index 0000000..208f140 --- /dev/null +++ b/APIs/schemas/NcParameterConstraints.json @@ -0,0 +1,22 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcParameterConstraints", + "description": "Abstract parameter constraints class", + "type": "object", + "required": [ + "defaultValue" + ], + "properties": { + "defaultValue": { + "type": [ + "number", + "string", + "boolean", + "object", + "array", + "null" + ], + "description": "Default value" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcParameterConstraintsNumber.json b/APIs/schemas/NcParameterConstraintsNumber.json new file mode 100644 index 0000000..c5a8deb --- /dev/null +++ b/APIs/schemas/NcParameterConstraintsNumber.json @@ -0,0 +1,51 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcParameterConstraintsNumber", + "description": "Number parameter constraints class", + "allOf": [ + { + "$ref": "NcParameterConstraints.json" + } + ], + "type": "object", + "required": [ + "maximum", + "minimum", + "step" + ], + "properties": { + "maximum": { + "type": [ + "number", + "string", + "boolean", + "object", + "array", + "null" + ], + "description": "Optional maximum" + }, + "minimum": { + "type": [ + "number", + "string", + "boolean", + "object", + "array", + "null" + ], + "description": "Optional minimum" + }, + "step": { + "type": [ + "number", + "string", + "boolean", + "object", + "array", + "null" + ], + "description": "Optional step" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcParameterConstraintsString.json b/APIs/schemas/NcParameterConstraintsString.json new file mode 100644 index 0000000..76ac68f --- /dev/null +++ b/APIs/schemas/NcParameterConstraintsString.json @@ -0,0 +1,35 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcParameterConstraintsString", + "description": "String parameter constraints class", + "allOf": [ + { + "$ref": "NcParameterConstraints.json" + } + ], + "type": "object", + "required": [ + "maxCharacters", + "pattern" + ], + "properties": { + "maxCharacters": { + "type": [ + "number", + "null" + ], + "description": "Maximum characters allowed" + }, + "pattern": { + "anyOf": [ + { + "$ref": "NcRegex.json" + }, + { + "type": "null" + } + ], + "description": "Regex pattern" + } + } +} \ No newline at end of file diff --git a/APIs/schemas/NcString.json b/APIs/schemas/NcString.json new file mode 100644 index 0000000..fb2d517 --- /dev/null +++ b/APIs/schemas/NcString.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "NcString", + "description": "Primitive UTF-8 string", + "type": "string" +} \ No newline at end of file diff --git a/APIs/schemas/base.json b/APIs/schemas/base.json new file mode 100644 index 0000000..8b5908e --- /dev/null +++ b/APIs/schemas/base.json @@ -0,0 +1,14 @@ +{ + "type": "array", + "description": "Describes the Configuration API base resource", + "title": "Configuration API base resource", + "items": { + "type": "string", + "enum": [ + "rolePaths/" + ] + }, + "minItems": 1, + "maxItems": 1, + "uniqueItems": true +} \ No newline at end of file diff --git a/APIs/schemas/properties-base.json b/APIs/schemas/properties-base.json new file mode 100644 index 0000000..03d736a --- /dev/null +++ b/APIs/schemas/properties-base.json @@ -0,0 +1,10 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "array", + "description": "Describes the Configuration API /rolePaths/{rolePath}/properties base", + "title": "Configuration API /rolePaths/{rolePath}/properties base", + "items": { + "type": "string" + }, + "uniqueItems": true +} \ No newline at end of file diff --git a/APIs/schemas/property.json b/APIs/schemas/property.json new file mode 100644 index 0000000..1d397fe --- /dev/null +++ b/APIs/schemas/property.json @@ -0,0 +1,15 @@ +{ + "type": "array", + "description": "Describes the Configuration API /rolePaths/{rolePath}/properties/{propertyId}", + "title": "Configuration API /rolePaths/{rolePath}/properties/{propertyId}", + "items": { + "type": "string", + "enum": [ + "value/", + "descriptor/" + ] + }, + "minItems": 2, + "maxItems": 2, + "uniqueItems": true +} \ No newline at end of file diff --git a/APIs/schemas/rolePath.json b/APIs/schemas/rolePath.json new file mode 100644 index 0000000..b13a0b1 --- /dev/null +++ b/APIs/schemas/rolePath.json @@ -0,0 +1,17 @@ +{ + "type": "array", + "description": "Describes the Configuration API /rolePaths/{rolePath}", + "title": "Configuration API /rolePaths/{rolePath}", + "items": { + "type": "string", + "enum": [ + "properties/", + "methods/", + "members/", + "descriptors/" + ] + }, + "minItems": 4, + "maxItems": 4, + "uniqueItems": true +} \ No newline at end of file diff --git a/APIs/schemas/rolePaths-base.json b/APIs/schemas/rolePaths-base.json new file mode 100644 index 0000000..0c8b3e3 --- /dev/null +++ b/APIs/schemas/rolePaths-base.json @@ -0,0 +1,10 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "array", + "description": "Describes the Configuration API /rolePaths base", + "title": "Configuration API /rolePaths base", + "items": { + "type": "string" + }, + "uniqueItems": true +} \ No newline at end of file diff --git a/examples/base-get-200.json b/examples/base-get-200.json new file mode 100644 index 0000000..33673cc --- /dev/null +++ b/examples/base-get-200.json @@ -0,0 +1,3 @@ +[ + "rolePaths/" +] \ No newline at end of file diff --git a/examples/properties-base-get-200.json b/examples/properties-base-get-200.json new file mode 100644 index 0000000..240e300 --- /dev/null +++ b/examples/properties-base-get-200.json @@ -0,0 +1,8 @@ +[ + "1m1/", + "1m2/", + "1m3/", + "1m4/", + "1m5/", + "1m6/" +] \ No newline at end of file diff --git a/examples/property-descriptor-get-200.json b/examples/property-descriptor-get-200.json new file mode 100644 index 0000000..5cf1072 --- /dev/null +++ b/examples/property-descriptor-get-200.json @@ -0,0 +1,57 @@ +{ + "description": "Descriptor which is specific to a block member", + "name": "NcBlockMemberDescriptor", + "type": 2, + "fields": [ + { + "description": "Role of member in its containing block", + "name": "role", + "typeName": "NcString", + "isNullable": false, + "isSequence": false, + "constraints": null + }, + { + "description": "OID of member", + "name": "oid", + "typeName": "NcOid", + "isNullable": false, + "isSequence": false, + "constraints": null + }, + { + "description": "TRUE iff member's OID is hardwired into device", + "name": "constantOid", + "typeName": "NcBoolean", + "isNullable": false, + "isSequence": false, + "constraints": null + }, + { + "description": "Class ID", + "name": "classId", + "typeName": "NcClassId", + "isNullable": false, + "isSequence": false, + "constraints": null + }, + { + "description": "User label", + "name": "userLabel", + "typeName": "NcString", + "isNullable": true, + "isSequence": false, + "constraints": null + }, + { + "description": "Containing block's OID", + "name": "owner", + "typeName": "NcOid", + "isNullable": false, + "isSequence": false, + "constraints": null + } + ], + "parentType": "NcDescriptor", + "constraints": null +} \ No newline at end of file diff --git a/examples/property-get-200.json b/examples/property-get-200.json new file mode 100644 index 0000000..4ec8726 --- /dev/null +++ b/examples/property-get-200.json @@ -0,0 +1,4 @@ +[ + "value/", + "descriptor/" +] \ No newline at end of file diff --git a/examples/property-value-get-200.json b/examples/property-value-get-200.json new file mode 100644 index 0000000..61bcdb5 --- /dev/null +++ b/examples/property-value-get-200.json @@ -0,0 +1 @@ +{ "value": "this is the property value" } \ No newline at end of file diff --git a/examples/rolePath-get-200.json b/examples/rolePath-get-200.json new file mode 100644 index 0000000..a8374fb --- /dev/null +++ b/examples/rolePath-get-200.json @@ -0,0 +1,6 @@ +[ + "properties/", + "methods/", + "members/", + "descriptors/" +] \ No newline at end of file diff --git a/examples/rolePaths-base-get-200.json b/examples/rolePaths-base-get-200.json new file mode 100644 index 0000000..ef2e2d0 --- /dev/null +++ b/examples/rolePaths-base-get-200.json @@ -0,0 +1,3 @@ +[ + "root/" +] \ No newline at end of file