Elements in link/relation ID

[Johannes Finsveen]

Hi Xavier

https://json-stat.org/full/#relationid  says
"When used to link to non-JSON-stat documents, the elements of the array are objects that can contain a type and an href property."
and "When used to link to JSON-stat documents, they can contain the common JSON-stat properties class, label, href and extension."

Does this mean a link to non-JSON-stat document should not contain an extension proprety or is "can contain a type and an href property" just examples?

When I put a document containing parts like this:
"dimension":{"Region": {...,
  "link":{"describedby":[{"extension":{"Region":"urn:ssb:classification:klass:104"}}]}}

into the https://json-stat.org/format/validator/ , it passes as valid.

BR,
Johannes

[Xavier Badosa]

According to the way the standard (and the validator) is written, what you suggest is legal. 

Because JSON-stat's "class" is more specific than media "type", "type" is not expected in a link to a JSON-stat document (we already know the type: application/json). But that's not necessarily true the other way around: non-JSON-stat document can benefit from JSON-stat "extension". So I would say that is legal to have an "extension" in a non-JSON-stat link.

The goal of the "link" element as it is conceived in the standard is to provide links in the form of URLs, which means that, even if it's not explicitly said, "href" must be considered "required" (in the docs "href" appears as optional but it refers to different "href" cases). Which means that using extension to provide a URN is ok but you probably should include an href also.

That said, because "extension" has no semantics attached to it, it seems to me that the structure in your example (extension inside an element of the relation ID property) unnecessarily complicated: 

"dimension":{"Region": {...,
  "link":{"describedby":[{"extension":{"Region":"urn:ssb:classification:klass:104"}}]}}

Instead, the following structure would probably be simpler (and more conformant with the standard): 

"dimension":{

    "Region": {

          ...,
         "link": {

              "describedby": [{

                    "type": "text/html",

                    "href" : "https://www.ssb.no/en/klass/klassifikasjoner/104"

               }]

         },

         "extension": {

              "urn": "ssb:classification:klass:104"

         }

    }

}

Xavier

[Johannes Finsveen]

Thank you, that is what I hoped for :-) 

 And thank you for the suggestion to simplify. The example was a simple one, the extension dictionary may have more entries and the keys may be a catagory like this:

      "link": {
        "describedby": [
          {
            "extension": {
              "KOSandel120000": "urn:ssb:contextvariable:common:f4f53d6f-6df7-4983-80c8-109edd92b87b:358053:KOSandel120000",
              "KOSandel150000": "urn:ssb:contextvariable:common:f4f53d6f-6df7-4983-80c8-109edd92b87b:358053:KOSandel150000",
              "KOSandel350000": "urn:ssb:contextvariable:common:f4f53d6f-6df7-4983-80c8-109edd92b87b:358053:KOSandel350000"
            }

, so I think the keys are needed to tell what the links applies to.

:-) J

[Xavier Badosa]

>   the extension dictionary may have more entries and the keys may be a category

Ok, but my main point was: "link" must contain an "href". Are you planning to include an "href" inside the "describedby" array? Besides, "extension" has to be thought of as a complement: it should not be the only info inside "describedby".

If you're not going to provide a URL then it's probably unnecessary to use "link". I understand that you want to benefit from the semantics of IANA's link relations, but that does not require "link" because the content and meaning of "extension" is up to you. You can even declare that "extension", when inside dimensions, accepts an IANA relation ID to provide URNs, like this:

"dimension":{

    "Region": {

          ...,

         "extension": {

              "describedby": [{

                    "KOSandel120000": "urn:ssb:contextvariable:common:f4f53d6f-6df7-4983-80c8-109edd92b87b:358053:KOSandel120000",

                    "KOSandel150000": "urn:ssb:contextvariable:common:f4f53d6f-6df7-4983-80c8-109edd92b87b:358053:KOSandel150000",
                    "KOSandel350000": "urn:ssb:contextvariable:common:f4f53d6f-6df7-4983-80c8-109edd92b87b:358053:KOSandel350000"

              }]

         }

    }

}

Or, if you're going to need to describe also the dimension besides its categories, you could use "describedby": { "category": [{ ... }] }.

X.

--
You received this message because you are subscribed to the Google Groups "json-stat" group.
To unsubscribe from this group and stop receiving emails from it, send an email to json-stat+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/json-stat/dfd8f1a2-649a-4543-8fd2-69b22734c2c7n%40googlegroups.com.

[Johannes Finsveen]

Sorry, I read too fast. I just saw "is legal". 

If we start with this:

         "describedby": [{
            "extension": {
              "Region": "urn:ssb:classification:klass:123",
              "Oslo": "urn:ssb:conceptvariable:vardok:672"
            }}],

 

Would this :

"link":{
         "related": [
            {
              "href": "https://www.ssb.no/klass/klassifikasjoner/123",
              "type": "text/html",              
              "extension": {
                    "attachment": "Region",
                    "relation": "definition-classification",
                    "metaid": "urn:ssb:classification:klass:123",
                    "label": "Classification for region."
               }
            }
            ,
            {
               "href": "https://www.ssb.no/a/metadata/conceptvariable/vardok/672/nb ",
               "type": "text/html",              
               "extension": {
                  {
                    "attachment": "Oslo",
                    "relation": "definition-value",
                    "metaid": "urn:ssb:conceptvariable:vardok:672",
                    "label": "Definition of Oslo"
                  }
                ]
              }
            }
          ]
      }
    },

be more in line with the intended use?  I use "related" not   "describedby" since that is already in use. The "attachment" takes the role of the key in the old extension dictionary.

Thank you again.

:-) J

 

[Xavier Badosa]

> I use "related" not   "describedby" since that is already in use. 

I feel I lack some context. To start with, I don't see where you are using "describedby". "related" is OK but it's less specific: you are using "related" to describe a relation that is better described using "describedby", I think.

Part of the context I'm also missing is where exactly you are planning to use all this. Will this information be included in a response of class "dataset"? Or of class "dimension"? In a "dataset" response it seems to me that this is too much information that is better handled through a pointer to a "dimension" response.

>  be more in line with the intended use?

Yes, nothing to object standardwise. But personally I think your proposal is too verbose and that the same informational goal can be accomplished in a simpler way. If the original goal was to attach URNs to dimensions categories, this would suffice:

"link":{
         "describedby": [

            {
              "href": "https://www.ssb.no/klass/klassifikasjoner/123",
              "type": "text/html",              
              "extension": {

                    "classification":  "urn:ssb:classification:klass:123",

                    "categories": ["urn:ssb:conceptvariable:vardok:672", ...]   //or "values" instead of "categories" if you prefer; you can also use an object (category id - URN) instead of an array.

               }
            }

A link is provided (where links to individual categories are probably offered) and for each category in the dimension a URN is offered. You can use a more complex structure to allow for future enrichment but it doesn't need to be much more complex:

              "extension": {

                    "definitions": {

                       "classification":  "urn:ssb:classification:klass:123",

                       "categories": ["urn:ssb:conceptvariable:vardok:672", ...]

                    }

               }

My point is: "label" or "attachment" don't seem to be needed as this is info already contained in the "dimension" element. And "relation" just to distinguish between classifications and values is better handled by separating those two. IMHO.

X.

To view this discussion visit https://groups.google.com/d/msgid/json-stat/4e57dda4-ada7-4414-8ba7-88bc18e1fcddn%40googlegroups.com.

[Johannes Finsveen]

My "in use" refers to that we have an old api and an old web gui which both can return the data as a jsonstat2 dataset  
with "link":{"describedby":[{"extension":{"Region":"urn:ssb:classification:klass:104"}}]}}
We are making new versions of the api and gui, where the api will be the datasource of the gui.
Since the new gui should to be "thin", the urns should preferably be resolved to external links that ready to use, but I agree its verbose.

Thanks,
:-) J