Open elf-pavlik opened 6 years ago
Is this in general about specifying the value type for template variables?
Yes, if we rely on hydra:property
in the mapping, possibly rdfs:range
of that property could help. At the same looking at hydra:freetextQuery
I think that 'unique identifier component' as a special case (possibly a common use case) may deserve a term in hydra:
vocab.
PROPOSAL: add something like hydra:uniqueIdentifierComponent
to the hydra vocab for use in IriTemplate
mapping
(smilar to hydra:freetextQuery
)
@lanthaler
What on earth is uniqueIdentifierComponent
? It sound awful specific. IMO we need something more generic.
Like you say, currently we have the hydra:property
term.
{
"@type": "IriTemplate",
"mapping": [
{
"@type": "IriTemplateMapping",
"property": "hydra:freetextQuery"
}
]
}
Strangely enough it doesn't have a range defined. But, I assume it's intended to be used with rdf:Property
and the data type of the mapped property should be taken from that property's range?
If so, maybe the simplest is to explicitly declare that if necessary. Even on an anonymous property?
{
"@type": "IriTemplate",
"mapping": [
{
"@type": "IriTemplateMapping",
"variable": "identifier",
"property": {
"rdfs:range": "??:uuid"
}
}
]
}
What’s the use case for this? Why does it need to be part of Hydra and not the domain vocabulary (e.g. schema.org)?
I'm not sure what you're asking actually.
Wrt the user case, I think that we lack a way to determine what is the data type of IriTemplate's variables. For example, you could get a template to filter a collection by selecting /events
from a single year
{
"@type": "IriTemplate",
"template": "/api/events{?year}",
"mapping": [
{
"@type": "IriTemplateMapping",
"variable": "year",
"property": "??"
}
]
}
There is no sensible term to put as hydra:property
because the year doesn't necessarily have to be a property of an Event
. In such case how does the client know that the year
variable should represent a year. And display the form control accordingly using some date picker etc.
Well, even if it would know that it is a year it wouldn't know what to do with it. Would it be the year the event is? The year the event was first announced? The year the event ended? The year the organizer of the event was born? The current year?
As much as I admire the M2M aspiration, in practice most of the time there will be human doing the "knowing". Provided the mapped variable includes a description. This is what most people expect from an API description
There is no sensible term to put as hydra:property because the year doesn't necessarily have to be a >property of an Event
Still i prefer a property over a raw type as it gives a context. Saying that the variable should be mapped to xsd:string
says nothing. Saying that that variable should be mapped to hydra:freetextQuery
sasy everyhing. The property should define the type of value (question is on how to do this - RDFS, OWL, SHACL?) and gives a hint to the client that the value should come from the user input.
I was also experimenting wit custom properties for skip/take. And remember that even for a variable mapped to a property that actually exists within the event
type, it still may be taken from somewhere else.
What on earth is uniqueIdentifierComponent? It sound awful specific.
I agree - it's way to fuzzy. Does it mean that the unique identifier is server side generated, or the client should come with a value on it's own. Also, for i.e. integer identifiers, how the client can come up with a value?
I need a way to instruct client to generate a collision save unique identifier, for example UUID or CUID, and substitute with it a particular variable in the URI Template.
In case of slug HTTP header AFAIK server does NOT guarantee that it will use that slug in generated IRI. With UC#5.1 creating event with PUT, which relies on schema:name
. Client most likely has to implement mechanism to recover from failed conditional put - when collision happens. So in practice client may find itself in a position that it simply can not use the value of schema:name
in the payload because of collision. I find unique identifiers like UUID or CUID convenient because they stay collision safe and allow applications working offline to mint IRIs and interlinking that data before syncing it up with the service. During the sync, payloads of PUT requests will already have @id
(which includes that unique identifier component) and will not include that component as value of any property in the payload.
What’s the use case for this? Why does it need to be part of Hydra and not the domain vocabulary (e.g. schema.org)?
How would you answer those questions for hydra:freetextQuery
?
hydra:freetextQuery A property representing a freetext query. Range: undefined Status: testing
For this case, we could actually use schema:query
For GUID / UUID / CUID I could actually propose to schema.org adding them as sub-properties of schema:identifier
How would you answer those questions for hydra:freetextQuery ?
I would remove this as there now exists something better in the form of schema:query along with schema:SearchAction
I agree with @lanthaler that a UUID requirement is something Hydra doesn't need a way to specify out of the box. If it can be added as a sub-property of schema:identifier
, that would be the best solution, imho.
Please verify my understanding. The variable mapping will only ever use the property
predicate:
{
"@type": "IrITemplateMapping",
"variable": "identifier",
"property": "schema-hypothetical:UUID-identifier"
}
We expect the client to find the description of schema-hypothetical:UUID-identifier
in the Api Documentation (or dereference it?) if it wants to find out about the rdfs:range
of that property?
In app I work on I will just rely on having understanding of property like schema:cuid
(or whatever ones we can get defined there), rdfs:range
doesn't help here since it would stay xsd:string
, in case of schema.org most likely it will have schema:cuid schema:rangeIncludes schema:Text
In many cases service will want to instruct client to generate UUID or CUID
In some cases server may also want to instruct client to provide slug, in that case we might want to look into https://www.w3.org/2011/http-headers#slug