Sinopia Functional Requirements & Constraints
Sinopia user requirements are captured and prioritized here: https://github.com/ld4p/sinopia/issues. Those GitHub repository issues should be considered the canonical source for Sinopia Phase 1 Work Cycle user requirements. A project board view (mixed with technical and other tickets) is available here: https://waffle.io/LD4P/sinopia.
Below is a brief overview of derived functional requirements to help contextualize our Sinopia Phase 1 Work Cycle MVP (minimum viable product) and acceptance criteria.
Metadata profiles, generally referred to as “Profiles” in the Sinopia project, are JSON documents that specify Sinopia Editor interactions vis-a-vis a generated form GUI for entering and interacting with entity data to be saved within Sinopia. For Sinopia Phase 1, we have the following functional requirements & constraints:
- Constraint: Keep development on Profile Editor to minimum.
- Constraint: Limit Profile Editor to only respond with the Profile’s JSON to a user for them to save, not save in the Profile system.
- Constraint: Profile Editor should mostly work with pre-existing Profiles (i.e. only perform minor updates that change the Profile JSON specification for backwards compatibility).
- Requirement: Ability to create new and update existing Profiles.
- Requirement: End-user (non-developer) can perform the above actions in a user-friendly, web-based GUI (i.e. the Profile Editor).
- Requirement: The Profile needs to map each generated form field to a:
- data input type (i.e. string, URI, integer, hash);
- subject resource variable the specific form field input should be asserted against (i.e. what the entered data is describing);
- predicate URI the form field represents.
- Requirement: The Profile specification should support:
- the addition of help text or descriptions for each form field specified.
- the addition of Profile metadata (e.g. schema and/or content standard adherence; who created the profile; when the profile was created or updated; etc.).
- translation of entered data to RDF should support translation to classes and predicates from any RDF-based ontology or vocabulary.
- a default subject resource variable for the Profile or a Profile form field block (delineated group of form fields).
- the ability to describe multiple subject resource variables across multiple form fields.
- the ability to specify contextual nodes (including blank nodes) for some form field values.
- indication if a form field is required and if a form field is repeatable.
- an optional form field default value.
- a form field being limited to an external vocabulary (pulled in via Lookup).
- a form field being limited to controlled values from a provided list of possibly values.
- Requirement: The Profile Editor should support reordering fields and groups of fields within a Profile (and in the derived form view).
- Request: Specify that the allowed values for a field depend on the value entered in another field when metadata is created
- Request: The Profile should support Group related fields into a section and give the section a name
- Request: The Profile Editor should allow importing an existing Profile, then copying those values to an entirely new Profile, as a template-based starting point for creating a derived Profile.
- Request: The Profile should support specification of filtering external lookups (i.e. for a given Lookup endpoint, further subdivide the possibly responses).
- Request: Profiles should be specified as JSON-LD, JSON Schema, and/or ShEx instead of JSON.
Sinopia Entity Data CRUD (Create, Read, Update, Delete) via Editor Front-end
With a Profile in hand, a user would load that Profile into the Sinopia Editor to then create, update, or possibly delete metadata about Sinopia entities. For Sinopia Phase 1, we have the following functional requirements & constraints:
Upon data being created in Sinopia, or when creating new data that should be linekd externally, there are a number of data exposure requirements. The functional requirements around data exposure (and, to a lesser degree, bulk data import) are listed below:
- Requirement: The Sinopia System must have programmatic interfaces for singleton & bulk load and retrieval of Sinopia entities. This is part of a requirement to make Sinopia an easily integratabtle component in larger data systems.
- Request: Sinopia entities should be dereferenceable, and the data should be viewable in multiple RDF serializations.
- Requirement: Sinopia entities must be searchable via simple keyword search and via limited faceted search by Users looking to create, update, clone, or link to Sinopia resources. This includes both search UIs and Sinopia Editor form lookups.
- Requirement: External entities in QA-supported vocabularies must be searchable via simple keyword search by Users looking to create, update, clone, or link to these resources within Sinopia. This includes both search UIs and Sinopia Editor form lookups.
- Constraint: Sinopia is not building a public discovery interface for Sinopia data.
- Query
Administrative Metadata Facets
Basic BIBFRAME Metadata Facets
Keyword Search across Metadata
Sinopia Server
Underlying all of the above is a Sinopia Server that manages & persists Sinopia resources. The following are functional requirements derived or inferred based on the above:
- Requirement: CRUD entity (singleton and bulk / graph) within the appropriate authorization group
- Proposal: Create JSON-LD Graph for resource(s) defined via the Metadata Profile to load into a certain group’s graph with skolemization of any blank nodes from the Sinopia Editor system to persistence.
- Requirement: Atomic & change-aware CRUD of Entity(s) within appropriate Group
- Requirement: Server must handle or propose pattern to clients for keeping untouched statements about an entity while other statements are added or updated about that same entity (i.e.
GET
before POST
).
- Requirement: Server must notify clients when relevant entities have changed between Server requests if the second request is an update (i.e.
PUT
, POST
, PATCH
, DELETE
, etc.).
- Requirement: The server must persist, and should generate, administrative metadata about entities and entity data created within the client. Administrative metadata includes but is not limited to: Who, When, Actions, Entities changed (to statement level), Group, Profile(s) used to create statements about resource.
- Proposal: Export of Sinopia data & metadata should allow (and optimize for) the following:
- Export all Entities from Group (data and metadata).
- Export all Entities from the Sinopia server (data and metadata).
- Proposal: The Sinopia Server manages entity URI minting for Sinopia entities, with the Sinopia domain, and an authorization group path, and a relative identifier for the entity as the file path of the URI.