How to define relation between schemas i.e. URI vs JSON Reference?

[Donghwan Kim]

Hi,

I saw that schema uses JSON Reference (https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) to reference other schema from advanced example of http://json-schema.org/ for embedding usage, however, if some schema should have 1:1 or 1:n relation with other schema, then is it suitable to use reference object in this case? or is simple URI preferred?

For example, if multiple student instances (defined by Student schema) should reference the same dog instance (defined by Dog schema), student.dog can be either {$ref: 'http://api.server.com/dogs/1234'} which is in the form of JSON reference or http://api.server.com/dogs/1234 which is just a URI. Assume that both instances are accessible as a HTTP resource in terms of REST API.

Student schema would be like the followings:

The first case - dog as a JSON reference

{
  type: "object",
  properties: {
    dog: { // JSON reference
      type: "object",
        properties: {
          $ref: {
            type: "string"
          }
        }
      }
    }
  }
}

The second case - dog as a URI

{
  type: "object",
  properties: {
    dog: { // URI
      type: "string"
    }
  }
}

Which way is recommended for this case in general? BTW personally I hope it's possible to define a new type for this use case like dog: {type: "reference", $ref: "/schemas/Dog"}. Is it possible?

Thanks,

-- Donghwan

[Jason Desrosiers]

I'm not sure I accurately understand what you are asking here, but I do my best to provide an answer.

It looks like you are trying to write a schema that describes a JSON Reference.  This is unnecessary.  The JSON References should be expanded BEFORE any JSON Schema validation is performed.  Therefore, it is unnecessary to describe the JSON Reference in the JSON Schema.

For example, assume the existence of the following resources.

http://example.com/schema/foo-bar

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "foo": { "$ref": "http://example.com/schema/foo" }
    "bar": { "$ref": "http://example.com/schema/bar" }
  }
}

http://example.com/schema/foo

{
  "type": "object",
  "properties": {
    "value": { "type": "string" }
  }
}

http://example.com/schema/bar

{
  "type": "object",
  "properties": {
    "value": { "type": "integer" }
  }
}

http://example.com/schema/foo-bar/asdf1234

{
  "id": "asdf1234",
  "foo": { "$ref": "http://example.com/foo/1" },
  "bar": { "$ref": "http://example.com/bar/1" },
}

http://example.com/foo/1

{
  "value": "foo1"
}

http://example.com/bar/1

{
  "value": 9876
}

Lets say we want to validate http://example.com/schema/foo-bar/asdf1234 against schema http://example.com/schema/foo-bar.  First, all JSON References are expanded resulting in the following ...

http://example.com/schema/foo-bar/asdf1234

{
  "id": "asdf1234",
  "foo": { "value": "foo1" },
  "bar": { "value": 9876 },
}

http://example.com/schema/foo-bar

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "foo": {
      "type": "object",
      "properties": {
        "value": { "type": "string" }
      }
    },
    "bar": {
      "type": "object",
      "properties": {
        "value": { "type": "integer" }
      }
    }
  }
}

At this point, normal validation can occur without any knowledge of JSON Reference.  There was no need for the schema to be aware that the data could have a JSON Reference.

[Donghwan Kim]

Hi Jason,

I'm confused to the boundary between relation and embeddables in terms of JSON schema and reference. As far as I understand, object 1, {"id": "asdf1234", "foo": {"$ref": "http://example.com/foo/1"}}, and object 2, {"id": "asdf1234", "foo": {"id": "1", "value": "foo1"}}, are not the same and not made from the same schema. From the persistence point of view, object 1 has an one-to-one relation with 'foo' whose id is 1 and object 2 embeds an embeddable 'foo' whose id is 1. In other words, object 1 is the form which should be stored to database and object 2 is the populated form of object 1. And what I try to do is to define a schema for object 1 not object 2 apart from validation like defining a database schema (Of course it's derived from the schema).

So my question was whether object1.foo should be a JSON reference or URI. Since JSON schema has utilized JSON reference for embeddables, I thought the spec might have recommendations for relation as well.

Thanks,

-- Donghwan

[Jason Desrosiers]

As far as JSON Schema is concerned, object 1 and object 2 are the same object defined by the same schema.  I won't reiterate the explanation because I can't think of anything I could add to my previous explanation that could make it more clear.

As for the case of persistence, storing an object with a JSON Reference makes perfect sense.  It just doesn't make sense to define a JSON Schema that requires a JSON document to include a JSON Reference.

Another option for referencing one object from another is by defining links using JSON Hyper-Schema.  Personally, this is the option I prefer.

[Donghwan Kim]

Thanks for the clarification.

I'm sorry to hear that relations and embeddables from persistence context are not distinguishable in JSON Schema but totally admit that they don't have to be from the point of view of the structure of JSON data. So I think I have to compromise it to meet my requirements in some ways.

I agree JSON Schema describing a JSON Reference simply doesn't make sense, however, if object1 should be validated before being inserted to database, it's still required. For that I may be able to define a custom format keyword e.g. {type: 'object', format: 'reference'}.

Anyway, thanks for notifying me of JSON Hyper-Schema. I'll read it. Though, if you have time, could you give me some examples on object1.foo like schema and instance using JSON Hyper-Schema?

Thanks!

-- Donghwan

--
You received this message because you are subscribed to a topic in the Google Groups "JSON Schema" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/json-schema/LEvNPAI5TJc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to json-schema...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Jason Desrosiers]

You can always expand references to validate the data before inserting it into the database.  Once you ensure that it is valid, you can break it down to be stored in the database.  But, I can see how that could be inefficient and even impractical in some cases.

Here is how I would change the example I gave earlier using JSON Hyper-Schema instead of JSON Reference

http://example.com/schema/foo-bar

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },

    "foo": { "type": "integer" },
    "bar": { "type": "integer" }
  },
  "links": [
    {
      "rel": "expand",
      "href": "/foo/{foo}"
    },
    {
      "rel": "expand",
      "href": "/bar/{bar}"
    }
  ]
}

http://example.com/foo-bar/asdf1234

{
  "id": "asdf1234",
  "foo": 1,
  "bar": 1
}

All other resources are the same as the previous example.  This kind of pattern should look familiar to someone used to working with a relational database.