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?
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.
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.
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.
@Vance Shipley thanks for the response... the team have looked at this and think this link is talking about the schema references $ref and $dynamicref, as opposed to @schemaLocation, which from chapter 4 of "TMF630 REST API Design Guidelines Part 7" talks about schemas being addressable.
However, we understand though the @schemaLocation does not have to be a network-addressable URI but this depends on how the schemas will be made availabe to the calling systems... for instance, the suggestion you gave here: https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?MessageKey=b5c3e3c9-deaa-4378-a540-8f6341c77318&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer" title="https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?messagekey=b5c3e3c9-deaa-4378-a540-8f6341c77318&communitykey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer" href="https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?MessageKey=b5c3e3c9-deaa-4378-a540-8f6341c77318&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer" rel="noreferrer noopener" target="_blank" class="fui-Link ___1eya986 f3rmtva f1ewtqcl fyind8e f1k6fduh f1w7gpdv fk6fouc fjoy568 figsok6 f1hu3pq6 f11qmguv f19f4twv f1tyq0we f1g0x7ka fhxju0i f1qch9an f1cnd47f fqv5qza f1vmzxwi f1o700av f13mvf36 f1cmlufx f9n3di6 f1ids18y f1tx3yz7 f1deo86v f1eh06m1 f1iescvh fhgqx19 f1olyrje f1p93eir f1nev41a f1h8hb77 f1x7u7e9 f10aw75t fsle3fq f17ae5zn">https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?MessageKey=b5c3e3c9-deaa-4378-a540-8f6341c77318&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer "Using Apache to serve static files would be an entirely acceptable method of distribution"
In our case, the API implementer, will host the schemas and as long as the API consuming systems supply the expected known GUIDs, then the schema to be applied can be deduced by the implementer.
But it sounds like we have implementations that work in different ways but all aiming to achieve the same result.