Support semantics in a <data-model>

[RaySinnema]

From @ApiSecRay on March 27, 2015 12:10

Allow mapping a property to some term in some vocabulary, like schema.org.

Copied from original issue: restful-api-description-language/radl-core#3

[jonathanrobie]

I'd like to see if we can simplify data-model before building it out. For instance, can we refer to an external JSON Schema for the data model? A lot of innovation is going on in Spring Data, ALPS, JSON-LD, etc., and I'm nervous about hard coding one approach into RADL. Especially an approach that involves using an XML schema language to describe what are generally JSON objects.

Perhaps the better approach is to do data modeling external to RADL and allow RADL to refer to a data model defined with JSON Schema or other technologies.

[RaySinnema]

The whole reason we have data-models is to be able to refer to it from within the RADL description, for instance from a state element. Can we do that when the data model is described in an external JSON Schema file? And if so, would that be convenient? Can we also then add semantics to individual elements in the data model?

Maybe you can post an example of what that would look like?

[jonathanrobie]

I think we need detailed use cases for data-models so we can be clear about the requirements. I really want to avoid adding any more functionality to them until we spend some time examining the requirements in more detail and considering ways to simplify them.

[RaySinnema]

The use case of this issue is to add semantics to the data items and then use that to generate an ALPS document or generate Spring code annotated with semantics.

[jonathanrobie]

We already have properties, and they can nest.

properties = element properties { documentation*, name, property* }
property = element property { name, documentation*, (properties* | text?) }

Could we use properties to generate an ALPS document or generate Spring code annotated with semantics? We could add URI identifiers to a property:

property = element property { name, uri?, documentation*, (properties* | text?) }
uri = attribute uri { xsd:anyURI }

[RaySinnema]

+1

[jonathanrobie]

We weren't able to discuss this on the call today, let me spin out a few more thoughts. If we use nested properties instead of a RELAX-NG schema, there are two logical places to do that in our model.

We currently allow nested properties directly in a state:

start-state = element start-state {
    documentation*,
    properties?,
    state-transitions?
}

state =
  element state {
    extends?,
    name,
    documentation*,
    properties?,
    state-transitions?
  }

That has the virtue that properties and state transitions are handled in a very similar manner, but it doesn't work well for properties used for input (which do not correspond to a state). We could change this by removing properties from states and using them only in data-models:

data-models = element data-models { data-model* }
data-model = element data-model {
    name?,
    documentation*,
    properties?,
    examples?
}

data-model-ref = attribute data-model { text }

If we did that, then we would modify states so that a data-model-ref is an optional attribute for a state:

start-state = element start-state {
    data-model-ref?,
    documentation*,
    state-transitions?
}

state =
  element state {
    extends?,
    name,
    data-model-ref?,
    documentation*,
    state-transitions?
  }

[RaySinnema]

+1

[gentlewind]

+1

[RaySinnema]

data-model = element data-model {
  name?,
  documentation*,
  properties?,
  examples?
}

Actually, it seems to me that a data model without properties makes no sense. So the ? after properties should be removed.

Also, to be in line with the rest of the schema, the name attribute should be mandatory as well.

[RaySinnema]

We also need a way to assign semantics to an entire data-model, or at least to a collection of properties. The latter may be confusing when the properties is wrapped inside another property, so I propose the former.

For instance:

<data-model name="product" uri="http://schema.org/Product">
  <properties>
    <property name="name" uri="http://schema.org/name"/>
    <!-- More properties -->
  </properties>
</data-model>

[jonathanrobie]

I don't think that the ? after properties should be removed. We have a permissive schema in general, and it's helpful to be able to develop a data model over time, starting with documentation or with examples or with the set of properties, and still process the result as valid XML. Warnings or errors can be issued later if there are no properties.

On Fri, Aug 7, 2015 at 1:55 AM, Rémon (Ray) Sinnema < notifications@github.com> wrote:

data-model = element data-model { name?, documentation*, properties?, examples? }

Actually, it seems to me that a data model without properties makes no sense. So the ? after properties should be removed.

— Reply to this email directly or view it on GitHub https://github.com/restful-api-description-language/RADL/issues/6#issuecomment-128606842 .

[jonathanrobie]

Can also have semantics, which are present when reused in various data models?

On Sat, Aug 8, 2015 at 5:07 AM, Rémon (Ray) Sinnema < notifications@github.com> wrote:

We also need a way to assign semantics to an entire data-model, or at least to a collection of properties. The latter may be confusing when the properties is wrapped inside another property, so I propose the former.

For instance:

— Reply to this email directly or view it on GitHub https://github.com/restful-api-description-language/RADL/issues/6#issuecomment-128942719 .

[RaySinnema]

I propose we make the name element mandatory and leave properties optional. We also add the uri attribute on the data-model level. (But see #31)

[gentlewind]

+1

[jonathanrobie]

See https://github.com/restful-api-description-language/RADL/issues/34