[JSON Schema] Support for schema.Reference

[smyrman]

UPDATED

This ticket is now about extending schema.Reference support in the schema/encoding/jsonschema package when adding support for the OpenAPI Specification (a.k.a. the Swagger 2.0. specification).

More specifically, schema.Reference fields should be encoded as {"$ref": "#definitions/<unique resource path>/id"} when encoding a schema for an OpenAPI Specification resource.

This might require:

• The ability to "name" a schema when adding it to the Index.
• Changes the schema.Reference or grant access to the Index to the encoder.
• The ability to turn on/off a JSON Schema encoding "extension".

PS! This ticket is currently blocked on adding initial support for the OpenAPI Specification.

[rs]

Yes, you can't modify the content of the reference from the parent document in the current state of the code.

[smyrman]

(...) As you can imagine, this poses a small problem, as we would presumably need access to the index.

For JSON Schema used with the Swagger 2.0 specification (a.k.a. OPEN API Specification), we can actually avoid the resource.Index dependency completely by using the "$ref" keyword. If we can accept no type to be defined when using JSON Schema without swagger, this solution could be good enough...

Swagger 2.0 defines all payloads for an API under the "definitions" parameter in the root schema. Therefore, we can refer to the ref validator schema definition as "myRef": {"$ref": "#/definitions/{TypeName}/id"}.

Note that {TypeName} is most correctly spelled singular and possibly capitalized, so it should not be taken directly from the reference path. The reference path can also be deep. This must however be solved anyway to enable Swagger 2.0 documentation, so it's not a Reference specific problem.

[smyrman]

UPDATE: if #100 is fixed/merged, there is an opportunity to access the Validator of the linked ID we are targeting if the schema is registered with a resource.Resource within a resource.Index that gets compiled.

This way we could embed an actual validator for the field rather than a reference, and we do not have to implement Swagger 2.0 support in order to close this issue.

[smyrman]

UPDATE: if #100 is fixed/merged, there is an opportunity to access the Validator of the linked ID we are targeting if the schema is registered with a resource.Resource within a resource.Index that gets compiled.

The way this has been implemented, the related validator is kept private. I want to revisit how JSON Schema (and ptentially other doc formats) gets generated after #77, so I am dropping this from the 0.2 milestone.