Why definitions using .js files?

[pmackay]

I'm just curious why this vocab definition is defining objects using .js files? What about just using JSON schema files to define simple objects?

[ahdinosaur]

hey @pmackay. we're using .js files that module.export extended JSON schema objects (with a few custom properties not in the spec but allowed by the spec). i chose .js files over .json files so i could do things like requires or getter functions, and if i wanted i could always add serialization to .json later. does that help?

[elf-pavlik]

IMO vocab should not assume any particular programming language! At he same time using JSON-LD similar to hydra-core makes sense to me. I offer my help with starting to write agent.jsonld 👷

[pmackay]

I think what would be great to make this vocab more accessible is data model documentation along the lines of http://www.popoloproject.com/. (I'm working on a similar thing here http://communitiesuk.github.io/waste-service-standards/models/ for the wildly exciting domain of local gov waste services).

[bhaugen]

@pmackay - I know more than one person who is wildly excited by waste services (actually, recycling).

But seriously, when the model here gets nailed down, we should do what you propose. And if you can help, having done it before, that would be even better!

[pmackay]

@bhaugen if you know anyone who might want to feed into specifications for recycling services, please connect us. Any input is very useful.

Happy to help if I can. The site I'm using/building is available here https://github.com/communitiesuk/waste-service-standards (I need to add docs on how its built). Uses http://www.mkdocs.org/, very nice project.

[ahdinosaur]

@elf-pavlik @pmackay: keen. :)

IMO vocab should not assume any particular programming language!

agreed. the plan in my head has always been to write npm scripts that use the modified json schemas in the .js files to export @context .jsonld, json-schema .json, hydra, etc. that way we have a single source of truth for the vocab, which we reflect over many interfaces. i only have limited capacity for all the things though, happy to collaborate with y'all on it.

I think what would be great to make this vocab more accessible is data model documentation along the lines of http://www.popoloproject.com/

yes! is json-schema an appropriate description to generate such data model documentation, or is there a better format? if we can agree on json-schema, a module to do json-schema to html documentation would be sweet. 🍯

[elf-pavlik]

AFAIK JSON Schema takes Closed-world Assumption, while Linked Data/RDF work with Open-world Assumption. With such mismatch I don't think we can use JSON Schema to define Linked Data vocabulary...

[pmackay]

@elf-pavlik I confess I'd need to see that explained with an example to understand the problem as you've described it there :-O

[ahdinosaur]

@elf-pavlik the way we're using JSON schema, by describing modular data models, seems to work really well for Linked Data/RDF. JSON schema by default assumes objects can have additional properties unless you specify additionalProperties is false, plus the schema language itself by default accepts any additional properties.

[elf-pavlik]

@ahdinosaur does it also assume that any property can have as its value an object of certain type or array of such objects?

{
  "name": "elf Pavlik",
  "seeks": { "@type": "Demand", "name": "foo" }
}

{
  "name": [ "elf Pavlik", "elf-pavlik" ],
  "seeks": [
    { "@type": "Demand", "name": "foo" },
    { "@type": "Demand", "name": "bar" }
  ]
}

[ahdinosaur]

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {
    "Demand": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string",
          "enum": ["Demand"]
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "seeks": {
      "anyOf": [{
        "type": "array",
        "items": {
          "$ref": "Demand"
        }
      }, {
        "$ref": "Demand"
      }]
    }
  }
}

i'm keen for a better solution, but JSON schema seems like the best interchange format that most of us are already using, it's simple and works well. in my own projects i intend to modify it with some sugar but i'll export it back to standard, or include any modifications that we all agree on (most likely additional meta-data related to Linked Data / RDF).

[elf-pavlik]

1. it seems that you can't have global definition of properties eg. "name"
2. it might require to always use "anyOf"

{
  "properties": {
    "name": {
      "anyOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ]
    },
    "seeks": {
      "anyOf": [
        { "$ref": "Demand" },
        { "type": "array", "items": { "$ref": "Demand" } }
      ]
    }
  }
}

etc. not to mention missing in your example

{
  "properties": {
    "@type": {
      "anyOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ]
    }
}

[bhaugen]

@pmackay - you might try Adam Johnson of Garbologie:
https://plus.google.com/u/0/+AdamJohnsonA/about
http://www.garbologie.com/

[elf-pavlik]

@ahdinosaur does JSON-Schema have any support for language maps for Literals (strings)?

• http://www.w3.org/TR/json-ld/#string-internationalization
• http://www.w3.org/TR/activitystreams-core/#naturalLanguageValues

[ahdinosaur]

@elf-pavlik true. that's why i'm keen to programmatically construct the standard JSON schemas from a modified, more opinionated JSON schema targeted at Linked Data / RDF. i've started schema-jsonld-context for converting our schema to context.jsonld files, but i'm hearing we also need to convert to schema.json files with some sugars to match JSON-LD:

• object references point to either one or many of a given type
• @type is either the type id or includes the type id
• object properties could be in a language map format

if not JSON schema, is there a description and validation language we can use as an alternative?

[elf-pavlik]

I would propose starting with JSON-LD file which uses RDFS & OWL for vocab definitions. When it comes to validations and form generations we may need to catch up on work in Data Shapes WG

• http://w3c.github.io/data-shapes/shacl/
• http://shexspec.github.io/ | www.w3.org/Brief/NDY1

[fosterlynn]

@ahdinosaur I need to understand why to even think about any other intermediate step. And if we are using some intermediate step, why to publish any of that, it seems to mostly have caused confusion? (I'm pretty sure I am missing something in the thinking since I am so new to this, so at this point asking just for information so I can even have an opinion.)

For example, for NRP, the library we installed takes in rdf triples and serializes it to json-ld output. But there is no place I would put those rdf triples for public viewing. And I created the context basically from examples and scratch, and although I didn't have time yesterday, these can be valicated using the jsonld playground, and of course when we do a pilot.

I'm thinking that what we need to publish is

1. a context file in json-ld format
2. a webpage such as w3c projects do (like http://www.w3.org/TR/activitystreams-vocabulary/) for human readable information, including descriptions, pics, examples in json-ld (and probably others), etc.

Is there anything else? What am I missing?

[fosterlynn]

@elf-pavlik sorry missed your post with mine, will check those too

[fosterlynn]

@ahdinosaur see the gitter conversation... elf trying to ping us....

[ahdinosaur]

I'm thinking that what we need to publish is

1. a context file in json-ld format
2. a webpage such as w3c projects do (like http://www.w3.org/TR/activitystreams-vocabulary/) for human readable information, including descriptions, pics, examples in json-ld (and probably others), etc.

that sounds great, let's do it. :)

• a context file in json-ld format
• a webpage such as w3c projects do (like http://www.w3.org/TR/activitystreams-vocabulary/) for human readable information, including descriptions, pics, examples in json-ld (and probably others), etc.

---

my other stuff is mad science for a single source of truth that generates all derivative truths, it's meant to be take in js schemas and output human and machine readable content, such as a context file in json-ld format or a webpage such as api projects do or object validation or database models or html forms or form validation or ...

feel free to ignore those files if it's confusing, maybe it'll make more sense once i do something more useful.

[elf-pavlik]

let's resolve it in valueflows/valueflows#35