Open APIs

I've had a question from the team about the "@schemaLocation" attribute and the reasons behind allowing this to be POST'able and patchable by the calling system. Can someone in the community help me with that explanation please?

The concern is the case where the TMF API provider wants to validate the incoming payload against an "allowed" schema. In this case, leaving the schema locaion up to the calling system would potentially present a violation, since the TMF API provider might be forced to validate a payload against a schema that is unrecognizable.

My team are leaning towards making the TMF API provider determine the schemaLocation based on the @type and other ids in the payload... but let me know what alternative approaches there are with this field.

cc @Mark Neil

Let's say you are producing TMF639 Resource Inventory API and I have implemented a resource orchestration Component. After instantiating our compound logical resources I want to publish them in your inventory. If you insist on a predefined set of schemas we have a brittle interface which requires coordinating all polymorphism supported by the orchestrator with your inventory Component.  That may be an unnecessary level of opinionation, what do we gain by paying that price?

I've had a question from the team about the "@schemaLocation" attribute and the reasons behind allowing this to be POST'able and patchable by the calling system. Can someone in the community help me with that explanation please?

The concern is the case where the TMF API provider wants to validate the incoming payload against an "allowed" schema. In this case, leaving the schema locaion up to the calling system would potentially present a violation, since the TMF API provider might be forced to validate a payload against a schema that is unrecognizable.

My team are leaning towards making the TMF API provider determine the schemaLocation based on the @type and other ids in the payload... but let me know what alternative approaches there are with this field.

cc @Mark Neil

This is a really tricky question, I think. Supplying a schema at runtime along with the data (and it doesn't matter if it's input or output) implies the the receiver of the data (API implementer for input, API consumer for output) will somehow be able to read the schema and reach a semantic understanding. That's quite a tall order for human-written software. But perhaps it's enough to expect that the data receiver will use the schema to validate the data contents, but not to understand what to do with this.

In Vance's example, let's suppose that you have defined a strongly-typed PhysicalResource - a WiFiRouter for instance. This might have strongly-typed properties IMEI, access point URL, credentials, etc. So Vance wants to send you an instance of WiFiRouter for you to store in your flexible repository, without understanding what a set top box is or what the properties mean, but you can, using the schema that he sent, ensure that the instance is valid syntactically.

@Vance Shipley feel free to contradict me if I have mangled your message.

Let's say you are producing TMF639 Resource Inventory API and I have implemented a resource orchestration Component. After instantiating our compound logical resources I want to publish them in your inventory. If you insist on a predefined set of schemas we have a brittle interface which requires coordinating all polymorphism supported by the orchestrator with your inventory Component.  That may be an unnecessary level of opinionation, what do we gain by paying that price?

I've had a question from the team about the "@schemaLocation" attribute and the reasons behind allowing this to be POST'able and patchable by the calling system. Can someone in the community help me with that explanation please?

The concern is the case where the TMF API provider wants to validate the incoming payload against an "allowed" schema. In this case, leaving the schema locaion up to the calling system would potentially present a violation, since the TMF API provider might be forced to validate a payload against a schema that is unrecognizable.

My team are leaning towards making the TMF API provider determine the schemaLocation based on the @type and other ids in the payload... but let me know what alternative approaches there are with this field.

cc @Mark Neil

Hi. Our intended approach is to ignore the incoming SchemaLocation but return it with the payload returned from the create operation as that URL can be determined from the internal processing of the payload. That way the caller will be presented with an accurate Schema that the data is conformant to. We arrived at this approach as we cannot guarantee the provided Schema Location is accessible or that the Schema at that location is correct.

This is a really tricky question, I think. Supplying a schema at runtime along with the data (and it doesn't matter if it's input or output) implies the the receiver of the data (API implementer for input, API consumer for output) will somehow be able to read the schema and reach a semantic understanding. That's quite a tall order for human-written software. But perhaps it's enough to expect that the data receiver will use the schema to validate the data contents, but not to understand what to do with this.

In Vance's example, let's suppose that you have defined a strongly-typed PhysicalResource - a WiFiRouter for instance. This might have strongly-typed properties IMEI, access point URL, credentials, etc. So Vance wants to send you an instance of WiFiRouter for you to store in your flexible repository, without understanding what a set top box is or what the properties mean, but you can, using the schema that he sent, ensure that the instance is valid syntactically.

@Vance Shipley feel free to contradict me if I have mangled your message.

Let's say you are producing TMF639 Resource Inventory API and I have implemented a resource orchestration Component. After instantiating our compound logical resources I want to publish them in your inventory. If you insist on a predefined set of schemas we have a brittle interface which requires coordinating all polymorphism supported by the orchestrator with your inventory Component.  That may be an unnecessary level of opinionation, what do we gain by paying that price?

I've had a question from the team about the "@schemaLocation" attribute and the reasons behind allowing this to be POST'able and patchable by the calling system. Can someone in the community help me with that explanation please?

The concern is the case where the TMF API provider wants to validate the incoming payload against an "allowed" schema. In this case, leaving the schema locaion up to the calling system would potentially present a violation, since the TMF API provider might be forced to validate a payload against a schema that is unrecognizable.

My team are leaning towards making the TMF API provider determine the schemaLocation based on the @type and other ids in the payload... but let me know what alternative approaches there are with this field.

cc @Mark Neil

I'm afraid your proposed behaviour isn't technically correct.

The JSON Schema specification identifies a schema with a URI Reference:

The resolved URI produced by these keywords is not necessarily a network locator, only an identifier. A schema need not be downloadable from the address if it is a network-addressable URL, and implementations SHOULD NOT assume they should perform a network operation when they encounter a network-addressable URI.

You should consider the value of @schemaLocation as an opaque identifier, which happens to have the form of a URI. If you ignore the incoming value (i.e. http://example.com/schema/WiFiRouter) and replace it with anything else (i.e. /my/schema/WiFiRouter) you have changed the schema entirely.

The value of @type is either a TM Forum Open API data model schema name, if @schemaLocation is absent, or it is as defined by the schema identifier provided by @schemaLocation.

Hi. Our intended approach is to ignore the incoming SchemaLocation but return it with the payload returned from the create operation as that URL can be determined from the internal processing of the payload. That way the caller will be presented with an accurate Schema that the data is conformant to. We arrived at this approach as we cannot guarantee the provided Schema Location is accessible or that the Schema at that location is correct.

This is a really tricky question, I think. Supplying a schema at runtime along with the data (and it doesn't matter if it's input or output) implies the the receiver of the data (API implementer for input, API consumer for output) will somehow be able to read the schema and reach a semantic understanding. That's quite a tall order for human-written software. But perhaps it's enough to expect that the data receiver will use the schema to validate the data contents, but not to understand what to do with this.

In Vance's example, let's suppose that you have defined a strongly-typed PhysicalResource - a WiFiRouter for instance. This might have strongly-typed properties IMEI, access point URL, credentials, etc. So Vance wants to send you an instance of WiFiRouter for you to store in your flexible repository, without understanding what a set top box is or what the properties mean, but you can, using the schema that he sent, ensure that the instance is valid syntactically.

@Vance Shipley feel free to contradict me if I have mangled your message.

Let's say you are producing TMF639 Resource Inventory API and I have implemented a resource orchestration Component. After instantiating our compound logical resources I want to publish them in your inventory. If you insist on a predefined set of schemas we have a brittle interface which requires coordinating all polymorphism supported by the orchestrator with your inventory Component.  That may be an unnecessary level of opinionation, what do we gain by paying that price?

I've had a question from the team about the "@schemaLocation" attribute and the reasons behind allowing this to be POST'able and patchable by the calling system. Can someone in the community help me with that explanation please?

The concern is the case where the TMF API provider wants to validate the incoming payload against an "allowed" schema. In this case, leaving the schema locaion up to the calling system would potentially present a violation, since the TMF API provider might be forced to validate a payload against a schema that is unrecognizable.

My team are leaning towards making the TMF API provider determine the schemaLocation based on the @type and other ids in the payload... but let me know what alternative approaches there are with this field.

cc @Mark Neil