Question: Structuring chid schemas of JSON Graph Format

[abargnesi]

Currently there is one known child schema of JSON Graph Format (BEL JGF for biological networks) and it lives within this repository. While this is a lightweight approach it will quickly be unmanageable.

My thought is to separate child schemas into their own repository under the jsongraph organization. This will allow the specification, examples, and test for that child schema to be isolated.

• Can we externally reference JSON Graph Format schema in the child to avoid duplication? How would this work if we wanted to extend just a node and/or an edge?
• Should we create a template to make it easy to create a child schema?

[RangerMauve]

AFAIK one can use $ref and point to schema URLs and point to specific definitions within one. One can then use something like allOf for extending a definition. docs. One thing to keep in mind is that not all validation libraries support fancy $ref magic right out of the box, so users of child schemas should be warned about this.

I'm not sure if I agree that all child schemas should be kept within the org, I think that if projects are extending the schema for their own purposes, it might make sense for them to keep it somewhere else. I think that the BEL JGF schema might make more sense if it was in its own repo with its own docs, though. Though, maybe it'd be nice to allow people to submit their schemas to be hosted on the website.

I thinkt hat the current BEL JGF schema would be a good enough template for people to start from for now.

[abargnesi]

I believe we can extend the JGF schema using the allOf keyword. For example we can add schema into graph.metadata like:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "properties": {
        "graph": {
            "allOf": [
                {
                    "$ref": "http://jsongraphformat.info/schema.json#/definitions/graph"
                },
                {
                    "type": "object",
                    "properties": {
                        "metadata": {
                            "properties": {
                                "valid": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "valid"
                            ]
                        }
                    }
                }
            ]
        }
    }
}

Two important points here:

• Use the allOf keyword to match against all schema in the value array.
• Reference the canonical JGF schema URL using $ref. The value is a JSON Reference.

An example document that would fail:

{
    "graph": {
        "metadata": {
            "valid": 1.0
        }
    }
}

And the failures:

[{
    ...
    "message": "instance failed to match all required schemas (matched only 1 out of 2)",
    "matched": 1,
    "nrSchemas": 2,
    "reports": {
        "/properties/graph/allOf/0": [],
        "/properties/graph/allOf/1": [{
            ...
            "message": "instance type (number) does not match any allowed primitive type (allowed: [\"boolean\"])",
            "found": "number",
            "expected": ["boolean"]
        }]
    }
}]

[wshayes]

Agreed - nice to have them in the org repo's for JGF but definitely not required - as long as the basic schema can be pointed to and validated against (probably need to provide some guidance on which validation libraries can handle $ref).

[abargnesi]

+1, I think we should accept requests to include schema URLs on the http://jsongraphformat.info/ site. This will help disseminate the applications of JGF.

[abargnesi]

@wshayes created #20 to add text around accepting schema URLs.

[abargnesi]

FYI, created https://github.com/jsongraph/bel-jsongraph-format to hold BEL JSON Graph Format. Removed from this repository.

[abargnesi]

Regarding a project template, maybe we should create a cookiecutter (or similar tool) template as a repository? We could model it after the bel-jsongraph-format repository.

[adifabio]

I am a fan of template based repositories. So I vote yes..(I also have no
problem using cookiecutter as we used it for some of out JQuery based
tools.)

On Wed, Aug 5, 2015 at 1:37 PM Anthony Bargnesi notifications@github.com
wrote:

Regarding a project template, maybe we should create a cookiecutter
https://github.com/audreyr/cookiecutter (or similar) template as a
repository? We could model it after the bel-jsongraph-format
https://github.com/jsongraph/bel-jsongraph-format repository.

—
Reply to this email directly or view it on GitHub
#19 (comment)
.

[abargnesi]

@jsongraph/owners

Ok, I wrestled with factoring out schema objects into the definitions section of JSON Schema and thought about how these could be reused in the child. I think I came out with some improvements.

To summarize the approach:

1. Factor out graph objects down to the node and edge.
2. Use allOf in the child schema to include parent schema and extend locally. Ultimately this means to customize metadata, but you need to replicate the object structure to get there.
3. Eliminate duplicated schema as you replicate the object structure of the parent.

An example with commentary is in this gist.

Can everyone look at this and update when you see some improvements?

[wshayes]

Closing due to inactivity