reconciliation-api / specs

Specifications of the reconciliation API
https://reconciliation-api.github.io/specs/draft/
30 stars 9 forks source link

Reformulate the `query` parameter as one of the `properties` in reconciliation queries #106

Closed wetneb closed 4 months ago

wetneb commented 1 year ago

The name to be matched in a reconciliation query is supplied in a dedicated field, the query one:

{
    "query": "Jane Doe",
    "properties": [
         {"pid":"date_of_birth", "v": "1967-07-06"}
    ]
}

On various occasions, it has come up that it could make sense to reformulate this as a special property, such as:

{
    "properties": [
         {"pid":"name", "v": "Jane Doe"},
         {"pid":"date_of_birth", "v": "1967-07-06"}
    ]
}

This would be useful for #101, or could also have provided a sensible solution to #27.

That being said, it does require introducing a sort of special property, which could conflict with the naming of other properties supported by the service. It is also a significant breaking change.

thadguidry commented 1 year ago

Why special at all? Entities have properties. Name is just one of many potential properties. And in that case, we could think to label the property in our specs something like "entityname" and likely avoid conflicts? But I am not strongly attached to any labeling of the terms in our specs for future as long as they align somewhat to the WD alias - item and name - property , RDFS, Schema.org properties somewhat.

Incidentally, the 2nd syntax code is similar somewhat in design with GraphQL object field querying and use of aliases

And kind of close to what OpenAPI notes as a MAY choose. In the request body, versus instead in a parameter object Ex. https://spec.openapis.org/oas/latest.html#example-object-examples

@fsteeg Does your org also have basic concept support of rdfs:label where https://schema.org/name is a subproperty of rdfs:label. And https://schema.org/alternateName is another property with subproperty https://schema.org/additionalName ?

@mixterj Do you have any strong opinions on this with any upcoming OCLC recon services? Basically, when a query is performed name or title or whatever are supplied as just properties like any other. Since I tthink before you said the services where mostly framed up with Elasticsearch then that would align quite well with it such as term or match since query is indeed documented as optional in their Search API:

query (Optional, query object) Defines the search definition using the Query DSL.