{"action":"created","issue":{"url":"https://api.github.com/repos/ga4gh/schemas/issues/311","labels_url":"https://api.github.com/repos/ga4gh/schemas/issues/311/labels{/name}","comments_url":"https://api.github.com/repos/ga4gh/schemas/issues/311/comments","events_url":"https://api.github.com/repos/ga4gh/schemas/issues/311/events","html_url":"https://github.com/ga4gh/schemas/issues/311","id":79704891,"number":311,"title":"Provide a JSON-LD context file or files","user":{"login":"cmungall","id":50745,"avatar_url":"https://avatars.githubusercontent.com/u/50745?v=3","gravatar_id":"","url":"https://api.github.com/users/cmungall","html_url":"https://github.com/cmungall","followers_url":"https://api.github.com/users/cmungall/followers","following_url":"https://api.github.com/users/cmungall/following{/other_user}","gists_url":"https://api.github.com/users/cmungall/gists{/gist_id}","starred_url":"https://api.github.com/users/cmungall/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cmungall/subscriptions","organizations_url":"https://api.github.com/users/cmungall/orgs","repos_url":"https://api.github.com/users/cmungall/repos","events_url":"https://api.github.com/users/cmungall/events{/privacy}","received_events_url":"https://api.github.com/users/cmungall/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-05-23T03:06:06Z","updated_at":"2015-05-23T23:46:36Z","closed_at":null,"body":"A [JSON-LD](http://www.w3.org/TR/json-ld/) context file provides an unambiguous machine-interpretable way to translate a JSON document to an RDF serialization. Even in cases where translation to RDF is not a desired goal, a JSON-LD document file can be a useful way of clarifying certain aspects of the GA4GH schema, such as how identifiers should be specified.\r\n\r\nBroadly speaking, the JSON-LD context file would provides mappings to RDF URIs for the following\r\n\r\n * The *keys* in a JSON/Avro object; for example, a key that specifies the position of a variant could be mapped to a FALDO property\r\n * The *values* in a JSON/Avro object; for example, an enum-type value could be mapped to an ontology class URI. Or, an ontology class ID can be mapped to its formal URI\r\n\r\nNote I am proposing this is adoped a non-invasive way. The JSON-LD context can be safely ignored by developers seeking to consume JSON, and the adoption of a JSON-LD schema should not affect modeling decisions in the Avro schemas. To make a JSON document JSON-LD all that is necessary is to add the \"@context\" object in the header, but even this should not be required; rather there should be a simple translation from the Avro-specified JSON to JSON-LD that adds this.\r\n\r\nOne area where immediate a GA4GH context file would immediately provide some clarification is in issue #165, where there is currently no consensus on the form for an ID to denote an ontology class. If the GA4GH uses [this OBO JSON-LD context](https://raw.githubusercontent.com/cmungall/biocontext/master/registry/obo_context.jsonld) or some subset of it, this would provide an unambiguous way of writing identifiers for any OBO library class.\r\n\r\nThe use of JSON-LD contexts was brought up by @tetron in the ever expanding discussion of #264, and may help clarify certain aspects of that discussion.\r\n\r\nA JSON-LD context file that provides complete coverage over all keys used in the union of all avro modules would be a larger task. This need not all be done at once, and need not be done as an 'official' GA4GH project (although it would be better to avoid the situation where we have competing JSON-LD contexts). \r\n\r\n"},"comment":{"url":"https://api.github.com/repos/ga4gh/schemas/issues/comments/104955251","html_url":"https://github.com/ga4gh/schemas/issues/311#issuecomment-104955251","issue_url":"https://api.github.com/repos/ga4gh/schemas/issues/311","id":104955251,"user":{"login":"tetron","id":1316612,"avatar_url":"https://avatars.githubusercontent.com/u/1316612?v=3","gravatar_id":"","url":"https://api.github.com/users/tetron","html_url":"https://github.com/tetron","followers_url":"https://api.github.com/users/tetron/followers","following_url":"https://api.github.com/users/tetron/following{/other_user}","gists_url":"https://api.github.com/users/tetron/gists{/gist_id}","starred_url":"https://api.github.com/users/tetron/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tetron/subscriptions","organizations_url":"https://api.github.com/users/tetron/orgs","repos_url":"https://api.github.com/users/tetron/repos","events_url":"https://api.github.com/users/tetron/events{/privacy}","received_events_url":"https://api.github.com/users/tetron/received_events","type":"User","site_admin":false},"created_at":"2015-05-23T23:46:36Z","updated_at":"2015-05-23T23:46:36Z","body":"An important thing to keep in mind, the json-ld context file needs to stay in sync with the avro schema that it maps from, which may be challenging if it has to be updated manually against an evolving spec.\r\n\r\nFor the common workflow language effort, which is associated with the ga4gh containers and workflows task team, we have been working on extending the avro schema language with annotations that enable automatic generation of the json-ld context and rdfs schema from the avro schema.  Example schema with annotations:\r\n\r\nhttps://github.com/common-workflow-language/common-workflow-language/blob/master/schemas/draft-2/cwl-avro.yml\r\n\r\nThe processing code is here:\r\n\r\nhttps://github.com/common-workflow-language/common-workflow-language/tree/master/reference/cwltool/avro_ld\r\n\r\nA few notes:\r\n\r\nThis is formatted using yaml instead of json for ease of writing inline documentation since yaml supports multiline string literals and plain json doesn't.\r\n\r\nIt supports data type definitions, I have not tried to use it with protocol definitions, but I don't expect much additional work would be required for the json notation.\r\n\r\nIt does not support the avro IDL syntax currently used to write most ga4gh schemas.  I'm not sure how best to go about implementing that.\r\n\r\nThe processor also implements record subclassing, abstract types, templates types with specialization, and documentation generation.  Example:\r\n\r\nhttp://common-workflow-language.github.io\r\n\r\nI am considering splitting this out from CWL to its own project, however to make it useful to the rest of ga4gh it would need outside contributors because my time is pretty limited."}}