propertyLinks (v5 proposal) - sgpinkus/json-schema GitHub Wiki

THIS WIKI IS OBSOLETE. PLEASE SEE THE NEW JSON-SCHEMA-ORG/JSON-SCHEMA-SPEC REPOSITORY.

---

Note: This proposal has been migrated to https://github.com/json-schema-org/json-schema-spec/issues/60

---

Proposed keywords

• propertyLinks

Purpose

Currently, we can describe the format of a parent object (with title/description/etc.), and we can describe the format of a child instance (with title/description/etc.) but we cannot describe the relationship between the two.

Motivating example

For instance, say you have an instance representing a programming project:

{
    "title": "AwesomeNet",
    "author": {
        "name": "Petra the Programmer",
        "homepage": "..."
    }
}

When describing the format for this instance, you can easily write a schema for the parent format:

{
    "title": "Programming project",
    "description": "A description of a programming project",
    "type": "object",
    ...
}

... and for the child format:

{
    "title": "Person"
    "description": "A representation of a person",
    "type": "object",
    ...
}

These are completely accurate descriptions of the format, but there is no way to express anything about the relationship between the two - considered on its own, the entry in "author" is indeed a "Person", but its relationship to the parent is more than that.

One current hack is to extend the "Person" format, so you can give it a title/whatever. However, that isn't really accurate - nothing has changed about the format at all, it's the parent-child link that's the interesting part.

Values

The value of propertyLinks would be an object. The values would themselves be objects, containing zero or more of the following properties:

• title - a name for the parent/child relationship
• description - a more detailed description of the parent/child relationship
• rel - a link relation (URI) representing the parent/child relationship

Example

Extending the "Motivating example" above:

{
    "title": "Programming project",
    "description": "A description of a programming project",
    "type": "object",
    "properties": {
        ...,
        "author": {"$ref": "/schemas/user"}
    },
    "propertyLinks": {
        "author": {
            "title": "Author",
            "rel": "http://schema.org/author"
        }
    }
}

Concerns

Duplicated keys

In that example, you end up listing "author" twice in the schema.

However, the alternatives are either an intermediate object (hard-to-read and not concise) or sticking extra info in the child schema (which requires ugly/awkward allOf extension, and still suffers from similar conceptual concerns to the existing workaround).