acdh-oeaw / arche-lib-disserv
A library providing dissemination services support on top of the acdh-oeaw/arche-lib
Installs: 3 904
Dependents: 3
Suggesters: 0
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^8.1
- acdh-oeaw/arche-lib: ^7
- zozlak/rdf-constants: ^1
Requires (Dev)
- phpstan/phpstan: *
- phpunit/phpunit: ^10
- zozlak/yaml-merge: ^1.0
README
A library implementing dissemination services on top of the arche-lib
Installation
composer require acdh-oeaw/acdh-repo-acdh
Documentation
API documentation: https://acdh-oeaw.github.io/arche-docs/devdocs/namespaces/acdhoeaw-arche-lib-disserv.html
Broader description of the dissemination services idea: https://acdh-oeaw.github.io/arche-docs/aux/dissemination_services.html
Dissemination service description schema
Dissemination service description is provided in RDF.
There are three classes of resources describing a service:
- The service itself
- required predicates:
- RDF class
https://vocabs.acdh.oeaw.ac.at/schema#DisseminationService
https://vocabs.acdh.oeaw.ac.at/schema#hasIdentifier
(URI) dissemination service identifier.https://vocabs.acdh.oeaw.ac.at/schema#hasTitle
(string) dissemination service name.https://vocabs.acdh.oeaw.ac.at/schema#serviceLocation
(string, exactly one value) provides a redirection URL template.
The template can contain parameter placeholders using the{name([@&]prefix)?(|trans)*}
syntax, where:name
is one ofRES_URI
/RES_URL
- the repository resource URL,RES_ID
- the internal repository resource identifier (the number being the last part of theRES_URL
),ID
- resource identifier, custom parameter placeholder name as described below&prefix
(requested prefix) or@prefix
(preferred prefix) allow to define value prefix. This can be useful if many values are expected, e.g. whenname
isRES_ID
. The actual prefix comes from the YAML config ($.schema.namespaces.{id}
).&prefix
and@prefix
behavior differs if no value matches a given prefix. In such a case&prefix
returns empty value while@prefix
returns any value.|trans
is optional chain of transformations like URL-encoding, extracting URI part, etc. You can check available transformations here. If a transformation takes additional parameters the syntax is|trans(p1,p2)
. Transformations can be chained, e.g.|trans1|trans2(p1)
. For real world examples see here.
https://vocabs.acdh.oeaw.ac.at/schema#hasReturnType
(string, one or more values) describes the returned data format. Technically it can be any string but the value should be easy to guess by users (so e.g. return mime type can be a good idea).
- RDF class
- required predicates:
- Matching rules
Rules describing how to find repository resources which can be processed by a given service.
All required rules and, if defined, at least one optional rule must match for the dissemination service to match.
In case of no rules being defined, all repository resources match a given dissemination service.- required predicates:
https://vocabs.acdh.oeaw.ac.at/schema#relation
(URI) pointing to the service'shttps://vocabs.acdh.oeaw.ac.at/schema#hasIdentifier
value.https://vocabs.acdh.oeaw.ac.at/schema#hasIdentifier
(URI) match rule identifier.https://vocabs.acdh.oeaw.ac.at/schema#hasTitle
(string) match rule name.https://vocabs.acdh.oeaw.ac.at/schema#matchesProp
(string, exactly one value) metadata predicate the rule is testing.https://vocabs.acdh.oeaw.ac.at/schema#isRequired
(bool, exactly one value) is this rule a required or an optional one?
- optional predicates:
https://vocabs.acdh.oeaw.ac.at/schema#matchesValue
(string, no more than one value) value required for the rule to match. If not provided, any value is accepted. All values are casted to string before the comparison.
- required predicates:
- Redirection URL template placeholders
Describe the way URL template placeholders are substituted with values.- required predicates:
- RDF class
https://vocabs.acdh.oeaw.ac.at/schema#DisseminationServiceParameter
https://vocabs.acdh.oeaw.ac.at/schema#relation
(URI) pointing to the service'shttps://vocabs.acdh.oeaw.ac.at/schema#hasIdentifier
value.https://vocabs.acdh.oeaw.ac.at/schema#hasIdentifier
(URI) parameter placeholder identifier.https://vocabs.acdh.oeaw.ac.at/schema#hasTitle
(string) parameter placeholder name (must match the name used in the redirection URL template!).
- RDF class
- optional predicates:
https://vocabs.acdh.oeaw.ac.at/schema#hasDefaultValue
(string, no more than one value) default value.https://vocabs.acdh.oeaw.ac.at/schema#usesRdfProperty
(string, no more than one value) RDF property from which the placeholder value will be taken.
- required predicates:
Example definition can be found here.
See also https://acdh-oeaw.github.io/arche-docs/aux/dissemination_services.html