Fix: #37. x-jsonld keywords.

[ioggstream]

This PR

• adds x-jsonld-type and x-jsonld-context Extensions to OAS 3.0
• these extensions are used to attach semantic information to OpenAPI 3.0 Schema Objects.
• fix Extension registry: x-jsonld-type and x-jsonld-object #37

Notes

• I successfully built the pages on docker.

[ioggstream]

As requested by @karenetheridge use openapi 3.2.0

[handrews]

I don't understand what's going on here. Are these just to work around the restriction on non-x- prefixed properties in OAS 3.0? If so, why does the example show openapi: 3.2 when you can just use @type and @context directly in OAS 3.1+ Schema Objects?

[ioggstream]

I don't understand what's going on here.
Are these just to work around the restriction on non-x- prefixed properties in OAS 3.0?

Those properties should be available at least for OAS3.0.

If so, why does the example show openapi: 3.2

Since these keyword should be available from OAS3.0+, I think they could be used even with OAS3.2. Reading the spec, I understand it is ok to do so.

when you can just use @type and @context directly in OAS 3.1+ Schema Objects?

Using @type and @context would just make a valid application/openapi+yaml file an invalid application/ld+yaml file ;)
I strongly advise against using @ in OAS/Schema files, since JSON-LD is widely used for data exchanges.

[handrews]

@ioggstream sorry for the delay in replying. My first reply was when I'd just woken up and I overlooked the reference to the I-D in the issue (if I even clicked through to the issue, which I might not have). I will read and respond properly as soon as I get a chance.

[handrews]

Sorry for the delay in getting back to this! No real concerns, but I do have a question about scope.

[handrews]

Based on your I-D, I see that this is primarily JSON Schema-oriented. But there are many API constructs where the description is spread across other types of Objects as well.

For example, while you might think of your form-encoded query string as one piece of data to model, it's actually split up over numerous Parameter Objects and Schema Objects.

Will restricting this to Schema Objects actually allow solving all of the semantic description use cases for an API?

[handrews]

@ioggstream any thoughts on this?

[ioggstream]

Hi @handrews,

TL;DR: for now only Schema Objects, eventually embedded/referenced in Parameter Objects. We tried to apply it to query strings, but it was too complex to get it right for implementers.

components:
  parameters:
    person:
      name: person
      schema:  # using $ref: is even better.
        type: object
        x-jsonld-type: Person
        properties:
          name: {type: string}

For example, while you might think of your form-encoded query string as one piece of data to model, it's actually split up over numerous Parameter Objects and Schema Objects.

Our preliminary tests showed that Parameters are very hard to get it right (i.e., model the information as JSON-LD/RDF in a way that is round-trip safe).
For example, the x-jsonld-type of the request may not fit just a single RDF class.

For this reason, we are currently limiting this to Schema Objects and supporting implementers in the adoption. Then we'll find a way to improve on Parameters' semantics without any early constraint.

The core idea for parameters was to model single strings (still Schema Objects)
iff they represent a specific URI (e.g. urn:isbn:123456789), bypassing the fact that JSON-LD only models JSON Objects and not scalar values. We should work on it in the next year.

[handrews]

Our preliminary tests showed that Parameters are very hard to get it right (i.e., model the information as JSON-LD/RDF in a way that is round-trip safe).

Arguably, it's not possible to model information as plain JSON and have it be round-trip-safe with parameters due to the lack of standardization regarding how to represent booleans, null, and numbers in string-based formats. If that's the problem you mean, in OAS 3.2 you can at least use examples with dataValue and serializedValue to establish a convention.

Anyway, this makes sense to me. Let me look over this all again as it's been a while, but we're probably good to go now.

[ioggstream]

how to represent booleans ...

This is also true!

[handrews]

@ioggstream it's been nearly six months since your last reply — is this still active or should we just close it? I think it's very close, my remaining questions are more about understanding the scope than anything else.