Can we replace current responseDataType with JSON-LD context?

[newgene]

Currently, the responseDataType is basically a keypath to ID-type-URI pairs:

          responseDataType:
            - elementPath: ec
              datatype: 'http://identifiers.org/ec-code/'
            - elementPath: ensembl.gene
              datatype: 'http://identifiers.org/ensembl/'
            - elementPath: ensembl.translation.protein
              datatype: 'http://identifiers.org/ensembl/'
            - elementPath: ensembl.translation.rna
              datatype: 'http://identifiers.org/ensembl/'
            - elementPath: entrezgene
              datatype: 'http://identifiers.org/ncbigene/'
            - elementPath: generif.pubmed
              datatype: 'http://identifiers.org/pubmed/'
            - elementPath: go.bp.evidence
              datatype: 'http://identifiers.org/eco/'
            - elementPath: go.bp.id
              datatype: 'http://identifiers.org/go/'

The keypath is flatten in order to provide a simple flat list.

Can we allow a JSON-LD context as the content for responseDataType, so that we can we can provide richer semantic context about the response data?

[cmungall]

Thanks, I'm trying to see how this maps to RDF. Is there already a proposed JSON-LD context for the fields above?

Am I correct in assuming that datatype should map to xsd:datatype? I think this may not work, and this was the essence of @micheldumontier's comments at the hackathon

[newgene]

Using this as an example:

{
   "symbol":  "CDK2",
   "ensembl": {
       "gene": "ENSG0000123374"
    }
 }

In JSON-LD 1.0, we can add context like this:

{
   "@context": {
	"symbol": "http://identifiers.org/hgnc.symbol/",
    "ensembl": "http://schema.mygene.info/ensembl/"
   },
   "symbol":  "CDK2",
   "ensembl": {
      "@context": {
          "gene": "http://identifiers.org/ensembl/"
      },
     "gene": "ENSG0000123374"
 }
}

Note that "@context" for ensembl needs to be embedded under "ensembl" field, which is not ideal.

In the coming JSON-LD 1.1, you can use "scoped context", so that we can put all nested context in one place:

{
  "@context": {
    "@version": 1.1,
    "symbol": "http://identifiers.org/hgnc.symbol/",
    "ensembl": {
      "@id": "http://schema.mygene.info/ensembl/",
      "@context": {
        "gene": "http://identifiers.org/ensembl/"
      }
    }
  },
  "symbol": "CDK2",
  "ensembl": {
    "gene": "ENSG0000123374"
  }
}

Much cleaner, as all context are now in one place.

Note that the JSON-LD 1.1 is not be supported in their JSON-lD play ground yet, but their Ruby client has supported all 1.1 features.

json-ld/json-ld.org#484
json-ld/json-ld.org#504

[newgene]

In my mind, we want to use JSON-LD to label what the fields are (by mapping them to the relevant URIs). That's a simple use case of JSON-LD.

JSON-LD itself can be much more powerful in term of representing RDFs, but I don't see how useful it is in our use cases (like the Translator project).

[newgene]

@micheldumontier regarding value-expansion in JSON-LD v1.1, here is the documentation: https://json-ld.org/spec/latest/json-ld-api/#value-expansion. Basically, it can be done using either @id or @vocab.

This is a closed relevant issue, json-ld/json-ld.org#369, showing an example with scoped @vocab for value expansion.

[cmungall]

@newgene when I pass this

{
   "@context": {
	"symbol": "http://identifiers.org/hgnc.symbol/",
    "ensembl": "http://schema.mygene.info/ensembl/"
   },
   "symbol":  "CDK2",
   "ensembl": {
      "@context": {
          "gene": "http://identifiers.org/ensembl/"
      },
     "gene": "ENSG0000123374"
 }
}

through jena rdfcat, I get

_:B5e96c6011cf511ec50a0606ee8a993d6 <http://identifiers.org/hgnc.symbol/> "CDK2" .
_:B5e96c6011cf511ec50a0606ee8a993d6 <http://schema.mygene.info/ensembl/> _:Ba69beea87bdd5e32a193486cb5adcd80 .
_:Ba69beea87bdd5e32a193486cb5adcd80 <http://identifiers.org/ensembl/> "ENSG0000123374" .

is this intentional? I would expect to have an ensembl URI

[cmungall]

In my mind, we want to use JSON-LD to label what the fields are (by mapping them to the relevant URIs). That's a simple use case of JSON-LD.

JSON-LD itself can be much more powerful in term of representing RDFs, but I don't see how useful it is in our use cases (like the Translator project).

I'm not really understanding the motivation here. The main reason to use JSON-LD would be if the goal was to produce linked-data / RDF.

If the goal is to produce a simple data dictionary, or tagging of identifier fields, maybe there are other solutions? I think I may be missing something, where is the best place to start with documentation of usage of JSON-LD in Smart-APIs? The website is great for learning how to register an API and edit the API, but I'm less clear on how JSON-LD is intended to fit in

[micheldumontier]

You can easily do the property expansion with "@id".
Value expansion currently depends on having "@type":"@id" to indicate an IRI value. The expansion can use the global "@base", or can be expanded only when using a prefixed identifier.
Take a look at the various formulations: http://tinyurl.com/y9ndsptw

There's no support for "@type": "@vocab" (a 1.1 feature) yet in json-ld playground, so i can't test a local value expansion.

Nevertheless, the bigger problem that I see is that if a web service places totally different identifiers in the value of a property, and doesn't use a prefix for each one, then your expansion will be wrong. That's why we went with the list formulation that started this thread - you can list all the different identifier types that could be in the value field.

[newgene]

@micheldumontier @cmungall FYI, I put up a test JSON-LD playground with the support of 1.1: http://jsonld.biothings.io/ (json-ld/json-ld.org#504), so that we can test more on the upcoming 1.1 features.

[newgene]

Nevertheless, the bigger problem that I see is that if a web service places totally different identifiers in the value of a property, and doesn't use a prefix for each one, then your expansion will be wrong. That's why we went with the list formulation that started this thread - you can list all the different identifier types that could be in the value field.

@micheldumontier, I believe you refer to the case like a field can have multiple id types as the value. For example, a "protein_id" field, which can be either Uniprot id or Ensembl protein id. Personally, I don't think this is a good practice, but I agree it does happen. In this case, this field should not be assigned to uniprot id type or ensembl_protein id type, because another API claims can handle Uniprot id will break when the input is ensembl_protein id. I think this field should be skipped for id type mapping (due to ambiguity) or should be assigned to a "new virtual" type (like "uniprot+ensembl_protein").

The solution for this case, I think either the developer fixes the ambiguity field and split it into two fields, or using the solution like CURIE (prefixed id values). If CURIE is used, I would map this field as the "CURIE" type, instead of the list of all supported ID types. And then other APIs taking CURIE ID as the input can be linked with this API via this field.

[newgene]

In my mind, we want to use JSON-LD to label what the fields are (by mapping them to the relevant URIs). That's a simple use case of JSON-LD.

JSON-LD itself can be much more powerful in term of representing RDFs, but I don't see how useful it is in our use cases (like the Translator project).
I'm not really understanding the motivation here. The main reason to use JSON-LD would be if the goal was to produce linked-data / RDF.

If the goal is to produce a simple data dictionary, or tagging of identifier fields, maybe there are other solutions? I think I may be missing something, where is the best place to start with documentation of usage of JSON-LD in Smart-APIs? The website is great for learning how to register an API and edit the API, but I'm less clear on how JSON-LD is intended to fit in

@cmungall Yes, one of the main motivations of JSON-LD is to use it as a serialization format between JSON and RDF. A simpler use-case for me is to use JSON-LD as a mechanism for tagging identifier fields, and also tagging the relationships (e.g. a drug id -->upregulates->uniprot id) and provenance if needed. Are there other established mechanisms/standards out there for this purpose? It's not hard to come up an own solution, but it would be better to use an existing (and well-adopted) standard. Plus that I really like the JSON-LD's nature of decoupling context and actual data, that lowers the barrier for creating a JSON-LD context for the existing API.

[micheldumontier]

@newgene I tried using the example that i provided earlier in the JSON 1.1 playground, but no change in the RDF that it generates...

i don't disagree that the JSON-LD augmentation is valuable, but we still need a mechanism to annotate the identifier types that are consumed or generated from a service which do not conform to JSON-LD expansion. If we commit to the JSON-LD scheme approach that you describe, then we are then saying that only those well formed APIs can be "smartAPIs".

also, can you show an example in how a json-ld context would be used in a swagger compliant description?

[NikkiBytes]

@newgene Is this still relevant?

[newgene]

Close this one as we now use x-bte OpenAPI extension to capture the semantic annotations of the JSON API response: https://smart-api.info/extensions#x-bte