diff --git a/oldcontent/api-spec/api-intro.md b/oldcontent/api-spec/api-intro.md deleted file mode 100644 index 20bf13f..0000000 --- a/oldcontent/api-spec/api-intro.md +++ /dev/null @@ -1,8 +0,0 @@ -# Introduction to the openDS API - -The API must comply with the requirements of the [Digital Object Interface Protocol (DOIP)](https://hdl.handle.net/0.DOIP/DOIPV2.0) specification published by the DONA Foundation. - - -*Specific requirements for DiSSCo to be written.* - -END. \ No newline at end of file diff --git a/oldcontent/faqs/faq.md b/oldcontent/faqs/faq.md deleted file mode 100644 index a6f8660..0000000 --- a/oldcontent/faqs/faq.md +++ /dev/null @@ -1,15 +0,0 @@ -# Frequently asked questions (FAQ) about Digital Specimens and the openDS approach - -## FAQs organised into categories - -We've provided answers to frequently asked questions about Digital Specimens, the openDS specification and the benefits of the openDS approach. The questions and answers are grouped into categories, each with its own page: - -- [Digital Specimens](faqds.md) -- [The openDS specification](faqopends.md) -- [The benefits of the openDS approach](faqbenefits.md) -- [openDS initiative compared to the Extended Specimens Network](faqcompare.md) - -For ease of reference, questions are numbered sequentially within each category i.e., Q101, Q102, ...;Q201, Q202, ...; Q301, Q302, ...; etc. - - -END. \ No newline at end of file diff --git a/oldcontent/faqs/faqbenefits.md b/oldcontent/faqs/faqbenefits.md deleted file mode 100644 index 4763094..0000000 --- a/oldcontent/faqs/faqbenefits.md +++ /dev/null @@ -1,31 +0,0 @@ -# Frequently asked questions (FAQ) about the benefits of the openDS approach - -**Q301. What are the benefits of the openDS approach?** - -There are multiple benefits to all sectors of the scientific community, society and the general public from the openDS approach. Many of these benefits are associated with specific use case examples. We give some examples below, but this is not an exhaustive list. - -- *Adding information to collections.* -In paleontology (for example, but not limited to that) some collections can contain many specimens that have not been identified. This can be because of lack of appropriate expertise within/of the collection owner or it may simply be due to lack of enough time and resources to do the work. Publishing the bare details of available specimens as Digital Specimens and allowing external experts to carry out identification and curation work on a community basis can add valuable information to an otherwise less informative collection. Of course, such work can be subject to moderation by a small number of responsible, expert persons. Such a community co-identification and/or co-curation approach can be attractive for engaging citizen experts from the wider public, as well as showing that scientists don’t yet know everything. Individuals can be acknowledged and recognised for work they perform. - -- *Enhancing value chains that begin in natural science collections.* -Open Digital Specimens (or ‘specimens on the Internet’) enhance the value chains that begin in natural science collections with the combination of the hard evidence (the physical specimens themselves) and the expertise that interprets that evidence. openDS extends the value chains from initial gathering and organisation of specimens, through conduct and commercialization of specific science based on specimens, to sharing the ensuing economic and social benefits in a fair and equitable way. Products of digital value chains provide the translational research evidence for regulatory processes in health, food, security, sustainability and environmental change, and new educational uses. Digital Specimens are essential for recently described notions of extended specimens [Webster 2017], next generation collections [Schindel 2018] and visions of virtual collections underlining research infrastructure initiatives such as Europe’s Distributed System of Scientific Collections (DiSSCo) and the One World Collection [Owens 2019]. In the future, new software applications can work with and on Digital Specimen objects to provide more sophisticated computer assistance to both the present day known work tasks and to unimaginable future works of collection specialists, scientists and other translational researchers working daily with specimens. - -- *Representing a physical thing in cyberspace (i.e., on the Internet) with context and meaning that allows processing in vast numbers by machines i.e., machine actionable, human readable.* -As a new kind of philosophical object alongside natural objects and fabricated tools, machine-actionable open Digital Specimen objects on the Internet are amenable to processing by and transport between heterogeneous information systems. Interoperability difficulties are much reduced through the type and operations definition mechanisms underlying the digital object concept. These objects are unambiguously identified by a persistent identifier (PID) mechanism that transcends changes in underlying Internet and World Wide Web technologies. Such objects have the implicit capability to remain findable, accessible, interoperable and reusable (FAIR) over timescales familiar to collection-holding institutions of many decades (100 years) and in this way integrate collection data in the data rich world of (*inter alia*) the Earth System Sciences and Life Sciences. - -- *Easy exchange of data between different information/computer systems.* - -- *Trusted, secure by design against unauthorised usage and/or modification.* -openDS, working together with the [Digital Object Interface Protocol (DOIP)](https://hdl.handle.net/0.DOIP/DOIPV2.0) specification brings digital specimen data out into the community, making them systematically organized mutable objects (units) with a standardized structure and representation to be shared, interpreted, annotated and acted upon by many. Implicit role-based access ensures that only those with authority can curate and modify the core data (what, where, when, who) whilst a wider range of approved individuals can easily supplement the core data with links to third-party sources, interpretations and annotations. - -- *Capturing and anchoring all the data derived from physical specimens.* -Digital Specimens are different from traditional databased specimen records in their ability as a container object to capture and anchor all the data derived from physical specimens by a multiplicity of processes that includes morphological, DNA, chemical, imaging analysis and many more. The key lies in distributed curation (without institutional boundaries) of open, authoritative packages of information linking all the different data classes back to the physical specimen from which they were derived; and in ensuring such packages, anchored with globally unique, persistent identifiers become the efficient and reliable, trusted and human- and machine-actionable source of scholarly data about a specimen. - -- *Can be referenced unambiguously when needed i.e., easily citable.* -Assignment and registration of unambiguous persistent identifiers to digital specimen information can begin immediately. *Natural Science Identifier* (*NSId*) names can be easily registered to immediately point to locations where authoritative units of specimen data can be found, in the same manner as DOIs locate journal articles; no matter where those are published or stored. - -- *Have the scale, form and precision required for modern data science (mining, analysis, inference).* - -- *Enabling new freedoms and opportunities arising from digital transformation of natural science collections.* - -END. \ No newline at end of file diff --git a/oldcontent/faqs/faqcompare.md b/oldcontent/faqs/faqcompare.md deleted file mode 100644 index 1efc1ca..0000000 --- a/oldcontent/faqs/faqcompare.md +++ /dev/null @@ -1,22 +0,0 @@ -# Frequently asked questions about the openDS initiative compared to the Extended Specimens Network - -**Q401. How is the openDS initiative part of the DiSSCo programme?** - -openDS, the Digital Specimen concept, and the persistent identifiers that unambiguously identify them are part of the [Distributed System of Scientific Collections (DiSSCo)](https://www.dissco.eu/) programme in Europe. The initiative aims to implement the Extended Specimen concept described by Michael Webster and colleagues in the 2017 book, "[*The Extended Specimen: Emerging Frontiers in Collections-Based Ornithological Research (Studies in Avian Biology)*](https://isbnsearch.org/isbn/9781498729154)" ![image of the book cover](/images/es-bookcover.png) whilst at the same time providing an enabling mechanism for the transformational change of working practices in collections-based science that DiSSCo foresees. - -**Q402. What is the Extended Specimen Network (ESN)?** - -The [Extended Specimen Network (ESN)](https://doi.org/10.1093/biosci/biz140) is an broad initiative by the [Biodiversity Collections Network (BCoN)](https://bcon.aibs.org/) in the USA to strengthen USA collections cyberinfrastructure by focusing on five main focus areas of collecting, digitization, integration/attribution, infrastructure, workforce and education of which the Extended Specimen concept is a key driving force; hence has an emphasis on both physical and digital representations. Alike in many respects, the ESN is akin to the overall DiSSCo programme to unify European natural science assets under common curation, access, policies and practices. - -**Q403. What are the technical similarities and differences between openDS and ESN?** - -DS and ES similarities and differences were explored in a [Birds of a Feather (BoF) session](https://www.tdwg.org/conferences/2020/working-sessions/#bof01:%20converging%20digital%20specimens%20and%20extended%20specimens%20-%20towards%20a%20global%20specification) convened during [TDWG 2020](https://www.tdwg.org/conferences/2020/). The session was recorded and is [available on YouTube](https://www.youtube.com/watch?v=8ljokNRkjeo). - -DiSSCo explains a Digital Specimen (DS) as a curated and authoritative open package of links to data associated with or derived from a physical specimen. As such, it is a ‘twin’ on the Internet for a specimen in a physical collection anchoring all the information known about or derived from that physical specimen. - -ESN explains an Extended Specimen (ES) as being the linkage between a physical specimen and all its derived preparation materials to all its local and externally derived digital products. - -Thus, DS and ES are conceptually very alike. Technical notions of how DS and ES might be implemented have emerged independently in Europe and the USA, giving rise to the openDS initiative and the Extended Specimen Network respectively. Nevertheless, with their common origin in the concept work by [Webster and colleagues](https://isbnsearch.org/isbn/9781498729154), they share the same basic idea and goals of connecting all the data derived from or about a physical specimen to that specimen in order to extend what is known about it. - - -END. \ No newline at end of file diff --git a/oldcontent/faqs/faqds.md b/oldcontent/faqs/faqds.md deleted file mode 100644 index a61b54b..0000000 --- a/oldcontent/faqs/faqds.md +++ /dev/null @@ -1,38 +0,0 @@ -# Frequently asked questions (FAQ) about Digital Specimens - -![Illustration of the data types tied up in physical specimens](/images/whatsinabug.png) - -**Q101. What is a Digital Specimen (DS)?** - -A Digital Specimen, referenceable by its unique Natural Sciences Identifier (NSId) represents the sum of information on the Internet about a natural specimen object. The Digital Specimen acts as a processable digital twin on the Internet for the physical specimen in a natural sciences collection (for example, in a Natural History Museum). - -This [DiSSCo Tech article](https://dissco.tech/2020/03/31/what-is-a-digital-specimen/) introduces the Digital Specimen concept in more depth. - -**Q102. What is an _open_ Digital Specimen?** - -The word ‘open’ is applied in the sense of an open format for Digital Specimens as defined by a published specification, the openDS specification. With the intention to improve interoperability, open formats can be used by anyone and their use is often encouraged within, by and for specific communities and the associated software applications and systems. - -From the perspective of the commons and the [Open Definition](https://opendefinition.org/), open can be applied further to mean that open Digital Specimens can be “_freely used, modified, and shared by anyone for any purpose_.” However, initial publication of Digital Specimen content is constrained by considerations of applicable legislative constraints, which in the bio- and geo-diversity domain is interpreted to mean that the aim with Digital Specimens is to be “_as open as possible, as closed as legally necessary_.” - -‘Open’ is also used in the sense that a Digital Specimen is a mutable digital object, meaning that it can be manipulated and modified by appropriately authorized persons. Open Digital Specimens ultimately act as a common curation space where experts should be able to contribute above and beyond the data held at the local level of a specific natural science collection. - -**Q103. How are open Digital Specimens represented?** - -Within an information system, the design of the internal data structures used to hold data associated with Digital Specimens is a decision for the system’s designers. However, the importance of being FAIR (‘findable, accessible, interoperable and reusable’) with its emphasis on machine actionability and the increasing use of object store infrastructures with their correspoinding APIs strongly advocates in the direction of using standardized, easily discoverable object type definitions such as the Digital Specimen object type. This is especially true at the external interfaces of systems. Knowing the (object type) definition of a Digital Specimen and what operations can be performed on it provides a shared and congruent understanding of the object context that is essential for correct functional operation and performance of systems, especially at the level of machine-to-machine interactions. Digital object type definitions and interface protocols directly support high levels of interoperability and reusability between systems and between applications. These are two of the four guiding principles of FAIR. To learn how Digital Object Architecture offers adherence to the FAIR principles as an integral characteristic, you may like to read this [paper by Lannom, Koureas and Hardisty](https://doi.org/10.1162/dint_a_00034). - -When it is necessary for transfer between different information systems, an open Digital Specimen can be represented (serialized) as a JSON document in which the various attributes of the specimen are represented as related sets of name/value pairs in [Javascript Object Notation (JSON)](https://www.json.org/json-en.html). The details of this transfer representation (serialization) are specified by the openDS specification. - -**Q104. How are Digital Specimens made FAIR (Findable, Accessible, Interoperable, Reusable)?** - -Digital Specimens are first-class [FAIR Digital Objects](https://fairdo.org/) (FDO), complying with the generic guidelines and requirements of the [FAIR Digital Object Framework](http://bit.ly/fdof102) ([Version 1.02, November 2019, FDOF Technical Implementation Guideline](https://github.com/GEDE-RDA-Europe/GEDE/blob/master/FAIR%20Digital%20Objects/FDOF/FAIR%20Digital%20Object%20Framework-v1-02.docx)). In this respect, they draw on controlled vocabularies and ontologies to introduce meaning (context) into their structure and are represented by object type definitions deposited in (a) public type registry(ies). - -**Q105. Can a Digital Specimen contain data for multiple specimens?** - -A Digital Specimen has a one-to-one relation with a physical specimen in a physical collection and corresponds to whatever the owning/holding institution deems to be an individual specimen. A specimen in this sense can be any object or entity (physical or conceptual) and is independent from categories such as preparation, sample or biological individual. - -If a specimen is a box container or spirit jar containing multiple organisms and that is catalogued as a single specimen, then it will have a single Digital Specimen as a digital surrogate for it. If each of the organisms in the box/jar is catalogued separately then each should have its own Digital Specimen surrogate with appropriate linking relations to the others within the same container. - -A Digital Specimen can correspond to a specimen that is no longer physically extant (e.g., lost, destroyed, split into specimens with separate identities, a fish released after taking measurements and samples, etc.). Such _status_ information should be made clear in the DS. - - -END. \ No newline at end of file diff --git a/oldcontent/faqs/faqopends.md b/oldcontent/faqs/faqopends.md deleted file mode 100644 index f52ec47..0000000 --- a/oldcontent/faqs/faqopends.md +++ /dev/null @@ -1,117 +0,0 @@ -# Frequently asked questions (FAQ) about the open Digital Specimens (openDS) specification - -**Q201. What is the openDS specification?** - -openDS is a specification of Digital Specimen and other related object type definitions essential to mass digitization of natural science collections and their digital use in a new generation of infrastructure and applications. For the principal digital object types corresponding to major categories of collections and specimens’ data, openDS defines the structure and content of each object type, and the operations that can act upon them. - -openDS is concerned with: i) the logical structure and content of Digital Specimen and other object types, and the operations permitted on them; ii) the handling rules and behaviors governing object operations in general; and iii) serialization and packaging for transfer between systems. openDS is not concerned with the implementation dependent aspects of storage, indexing and manipulation of different object types, nor with the application and usage dependent presentation of object content e.g., how a human sees data on a screen. - -**Q202. What is the purpose of the openDS specification?** - -The purpose of openDS and its specification is to enable new freedoms and opportunities for science that arise from digital transformation of natural science collections. openDS and the associated Natural Science Identifiers (NSId) for persistently identifying Digital Specimens are examples of ‘[enabling technology](https://en.wikipedia.org/wiki/Enabling_technology)’ i.e., an innovation that can be applied to drive radical change in the capabilities of a user or culture. Just as with the invention of the internal combustion engine around 170 years ago, no-one can see clearly all the freedoms and opportunities that will become possible. openDS and NSId should be seen as part of the emerging Internet of FAIR Data and Services that will grow alongside the existing Internet and World Wide Web. - -**Q203. What can openDS be used for and who would use it?** - -openDS can be used to guide design and implementation of infrastructure and its components, as well as software applications and process workflows. For example: - -- The serialization and packaging specifications can be used to guide software design for applications where Digital Specimens data must be transferred from one system to another or from one user to another. -- The openDS JSON Schema can be used to validate the structure and content of DS instances e.g., as they are serialized/packaged, or inserted in repositories. -- The Schema(s) can be used as the basis for design of internal data structures within specific components of the DS Architecture. - -openDS is principally intended for use by systems engineers and software developers involved in infrastructure, services/applications and workflows development. openDS will also be helpful to those scientists having an informatics component to their work, who may want to develop bespoke software and scripts to make use of or interact with Digital Specimen data directly. - -**Q204. How does openDS differ from Darwin Core and ABCD?** - -Darwin Core (DwC) and Access to Biological Collection Data (ABCD) are application level data schema specifications that support the exchange and integration of primary collection (and observation) data. - -openDS is like Darwin Core and ABCD insofar as it reuses several of the main data model concepts from those well-established specifications, as well as re-using terms where possible. - -openDS goes further than data exchange and integration to provide active (specimen) data management capability more generally. It does this by defining standard operations (beyond create, update, retrieve and delete) that can act on Digital Specimens to access/change their content; even to run algorithms on that content. This is implemented through a standard and secure method for interacting with digital objects, the [Digital Object Interface Protocol (DOIP)](https://www.dona.net/sites/default/files/2018-11/DOIPv2Spec_1.pdf). - -**Q205. Is openDS just Linked Open Data?** - -No. Linked (Open) Data is a mechanism for creating the Semantic Web, whereby data is interlinked with other data in a structured way such that it receives meaning and can be queried semantically by processing the actual relationships between information and inferring answer(s) to that query. - -openDS is an encapsulating approach that works at a more fundamental level. More than just linking data it ensures stable binding between informational entities required for machine actionability. However, openDS does include that the data within Digital Specimen objects is linked, such that the data receives meaning. - -In that sense, the data content of a Digital Specimen can be cast as RDF to a triple store if that is what is needed. - -**Q206. What about the implementation? What do I have to do?** - -*To be answered, from the data provider perspective (and others).* - -**Q207. What is the scope of openDS version 1.0?** - -openDS version 1.0 will be the first version of openDS. It is intended to support the compatibilities and service components summarized in the table below. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Standards - Compatibility -
Minimum information about a Digital Specimen (MIDS) - Support for all level 0 – 3 information elements, including presence of images and other media types. -
CETAF Specimen Preview Profile (CSPP) - Support for 13 CSPP information elements. -
- -
Services - Service component/functionality -
European Collection Objects Index (ECOI) - Collation of basic specimen information to support indexing, searching and presentation in human-readable and machine-readable (JSON-LD) forms. -
European Loans and Visits (ELViS) - Display of basic specimen information to support arrangement of loans and visits. -

-Association of loans and visits transaction events to their corresponding Digital Specimens. -

European Unified Annotation and Curation (ECAS) - Association of annotation and interpretation record events to their corresponding Digital Specimens. -
Provenance and attribution - Association of provenance events i.e., origins of the data and the processing/modifications applied) to their corresponding Digital Specimens. -
- -**Q208. Does openDS capture the change history of a Digital Specimen?** - -Capturing the change history of a Digital Specimen, especially the scientific activities that have been performed upon it (such as curation and annotation) is essential for establishing scientific provenance. - -Our provisional design proposal (October 2020) for openDS ensures that the primary (abstract) class definitions of openDS (Classes: Entity, Activity, Agent, Role, Transaction, Derived Data) align perfectly with the basic, three-axiom model based on PROV entities (Entity, Activity, Agent) as outlined in the [final recommendations of the RDA/TDWG Attribution Metadata Working Group](http://dx.doi.org/10.15497/RDA00029) to support standardized metadata for attributing work and tracking provenance in the curation and maintenance of research collections. - -**Q209. When will the openDS specification be available?** - -At the moment there is no explicit timeline for when the specification will be available. We hope to release working drafts during 2021. - - -END. \ No newline at end of file diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/auto-bio-schema.json b/oldcontent/json-examples-and-schemas/basic-image-object/auto-bio-schema.json deleted file mode 100644 index 544b7b4..0000000 --- a/oldcontent/json-examples-and-schemas/basic-image-object/auto-bio-schema.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - -} \ No newline at end of file diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/basic-image-object.md b/oldcontent/json-examples-and-schemas/basic-image-object/basic-image-object.md deleted file mode 100644 index 0b36058..0000000 --- a/oldcontent/json-examples-and-schemas/basic-image-object/basic-image-object.md +++ /dev/null @@ -1,36 +0,0 @@ -# Basic image object -## Introduction -The [Specimen Data Refinery (SDR)](https://github.com/DiSSCo/sdr) has a specific requirement for [a JSON Schema for image objects](https://github.com/DiSSCo/SDR/issues/17) as inputs and outputs of refinement workflows. - -Within this object, the image will be a payload file in jpeg format. This is accompanied by some basic information about the image, such as technical details of the image, the owning institution, the license for use of the image, etc. A controlled vocabulary is used to describe what the image contains. A PID is assigned automatically when the image object is first created. - -A controlled vocabulary can be used to describe what the image contains, it's segments, etc. A minimum might be the physicalspecimenId to be used in conjunction with the institution identifier. *(15 June 2021) These aspects are not yet shown in the example below.* - -Further fields are required later on. These will either provide additional information to accompany the image as it serves as an input to a workflow; and/or they can be enriched by specific workflow steps and filled as output of the workflow. These fields will be defined later. It is an open issue as to whether they are part of the image object type or a separate object type. It is also an open issue as to whether such fields should be based on/compatible with the TDWG [Audubon Core (AC)](https://www.tdwg.org/standards/ac/) vocabularies for representing metadata for biodiversity multimedia resources and collections. - -## Design -The initial design of openDS posits an 'i_section' of a Digital Specimen containing metadata about and references to images or the images themselves as payload files within the DS object. The i_section is represented by a self-contained `images` JSON object structure. - -The storage location and manner of storage of images is highly variable. Usually (today) images are to be found at the endpoint of a URI in a simple filestore or in a more sophisticated media management system. Increasingly, images can and will be served through, for example the Image and Presentation APIs of the [International Image Interoperability Framework (IIIF)](https://iiif.io/). The Presentation API in particular is oriented towards standardized descriptions of the structure, layout and presentation mode of compound digital objects. Further work is needed in DiSSCo to properly understand how to integrate IIIF and object server technologies and how to dynamically serve and manipulate specimen images. For now, we assume a straightforward delivery of static image files one-by-one. - -At hand also is a continuing thought process around the granularity of openDS objects. From one extreme of including all data in a single object to the opposite extreme of splitting up data into a large number of related tiny objects, it is still an open issue as to where an open Digital Specimen and its constituent parts sit on this spectrum. - -A first representation in [example 2](../digital-specimen-object/basic-json-example2.md)) is based on the idea of an open-ended array of image objects within an i_section object. But such an approach, when adopted for a specimen with many images (as in 3D stacked images, for example) or when applied in a similar manner to other data types of the open DS leads to rapid JSON expansion with significant repetition of common data elements. Nevertheless, each image and its pertinent metadata should be self-standing for the cases where that image alone is used. Again, for now we assume this is the case and treat images objects with a granularity of one i.e., one image per basic image object with the image file as the payload of the object. - -The i_section of an open Digital Specimen then will point to one or more basic image objects associated with the specimen rather than including those directly into the DS itself. Only the thumbnail image will be included directly to reduce the number of fetches from an object before deciding whether a specimen and its image are of any potential interest. - -## Artefacts -The following artefacts are associated with this basic-image-object description: -1. Example of an [basic image object](bio-example.json) (JSON file). -2. JSON [schema file auto-generated](auto-schema.json) from (1). -3. [openDS JSON Schema file](openDS-bio-schema.json) derived from hand-optimisation of (2) and [list of optimisations](bio-optimisations.md) applied. -4. [CORDRA schema file](bio-cordra-schema.json) (in JSON) derived from adaptation of (3) and [list of adaptations](bio-cordra-schema-adaptions.md) made. - -## Workflow steps -The following steps were taken to produce the artefacts listed above. -1. Create by hand the example of an [basic image object](bio-example.json) (JSON file). -2. Validate (1) using [JSONLint](https://jsonlint.com/). = valid JSON. -3. Autogenerate a schema ...Got to here>> - - -END. \ No newline at end of file diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/bio-cordra-schema-adaptions.md b/oldcontent/json-examples-and-schemas/basic-image-object/bio-cordra-schema-adaptions.md deleted file mode 100644 index e69de29..0000000 diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/bio-cordra-schema.json b/oldcontent/json-examples-and-schemas/basic-image-object/bio-cordra-schema.json deleted file mode 100644 index e69de29..0000000 diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/bio-example.json b/oldcontent/json-examples-and-schemas/basic-image-object/bio-example.json deleted file mode 100644 index ab1ddc6..0000000 --- a/oldcontent/json-examples-and-schemas/basic-image-object/bio-example.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "id": "20.5000.1025/64ae0cf0dacb7bd20ba5", - "typeName": "ODStypeBIO-1901", - "images": { - "availableImages": [ - { - "imageName": "hi-res", - "source": "#/payloads", - "mediaType": "image/jpeg", - "imageWidth": "400", - "imageHeight": "280", - "xResolution": "", - "yResolution": "", - "colorSpace": "", - "iccProfileName": "", - "creator": "", - "created": "", - "project": "", - "license": "CC BY 4.0" - } - ] - }, - "payloads": [ - { - "name": "hi-res", - "filename": "1427463506459UAeHPJw9jXoET1sF.jfif", - "mediaType": "image/jpeg", - "size": 15063 - } - ] - } \ No newline at end of file diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/bio-optimisations.md b/oldcontent/json-examples-and-schemas/basic-image-object/bio-optimisations.md deleted file mode 100644 index e69de29..0000000 diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/jsonObjGen-bio-regions.json b/oldcontent/json-examples-and-schemas/basic-image-object/jsonObjGen-bio-regions.json deleted file mode 100644 index 5da738a..0000000 --- a/oldcontent/json-examples-and-schemas/basic-image-object/jsonObjGen-bio-regions.json +++ /dev/null @@ -1,90 +0,0 @@ -{ - "id": "20.5000.1025/64ae0cf0dacb7ce30ba7", - "typeName": "ODStypeBIO-1902", - "images": { - "imageName": "7870917_5bb2274d436ebab560cb85b83ba21d89fa8bc065", - "source": "https://example.org/7870917_5bb2274d436ebab560cb85b83ba21d89fa8bc065.jpg", - "mediaType": "image/jpg", - "imageWidth": 8688, - "imageHeight": 5792, - "xResolution": 1450, - "yResolution": 965, - "colorSpace": 1, - "iccProfileName": "", - "creator": "NHM Digitisation Team", - "created": "2019-07-11T15:37:48.000Z", - "project": "SDR prototype", - "license": "CC BY 4.0" - }, - "payloads": [ - "name = thumbnail", - "filename = 1427463506459UAeHPJw9jXoET1sF.jfif", - "mediaType = image/jpeg", - "size n = 15063" - ], - "regions": [ - { - "name": "labelRegion", - "bounds": [ - [600, 4], - [900, 4], - [900, 9], - [600, 9], - [600, 4] - ], - "regions": [ - { - "name": "textlineRegion", - "bounds": [ - [600, 5], - [900, 5], - [900, 6], - [600, 6], - [600, 5] - ] - }, - { - "name": "textlineRegion", - "bounds": [ - [600, 6], - [900, 6], - [900, 7], - [600, 7], - [600, 6] - ] - }, - { - "name": "textlineRegion", - "bounds": [ - [600, 7], - [900, 7], - [900, 8], - [600, 8], - [600, 7] - ] - }, - { - "name": "textlineRegion", - "bounds": [ - [600, 8], - [900, 8], - [900, 9], - [600, 9], - [600, 8] - ] - } - ] - }, - { - "name": "barcodeRegion", - "bounds": [ - [600, 1], - [900, 1], - [900, 3], - [600, 3], - [600, 1] - ] - } - ] - } - \ No newline at end of file diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/jsonObjGen-bio-regions.txt b/oldcontent/json-examples-and-schemas/basic-image-object/jsonObjGen-bio-regions.txt deleted file mode 100644 index b2c5424..0000000 --- a/oldcontent/json-examples-and-schemas/basic-image-object/jsonObjGen-bio-regions.txt +++ /dev/null @@ -1,252 +0,0 @@ - -JSON generator = https://beta5.objgen.com/json - - -bounds - needs a composite pattern for embedding - -objgen language - -id = 20.5000.1025/64ae0cf0dacb7ce30ba7 -typeName = ODStypeBIO-1902 -images - imageName = hi-res - source = #/payloads - mediaType = image/jpg - imageWidth n = 400 - imageHeight n = 280 - xResolution n = - yResolution n = - colorSpace = - iiProfileName = - creator = - created = - project = SDR prototype - license = CC BY 4.0 -payloads [] = name = hi-res, filename = 1427463506459UAeHPJw9jXoET1sF.jfif, mediaType = image/jpeg, size n = 15063 -regions[0] - name = label - bounds [1] n = 100.0, 0.0 - bounds [2] n = 101.0, 0.0 - bounds [3] n = 101.0, 1.0 - bounds [4] n = 100.0, 1.0 - bounds [5] n = 100.0, 0.0 -regions[1] - name = barcode - bounds [1] n = 400.0, 0.0 - bounds [2] n = 401.0, 0.0 - bounds [3] n = 401.0, 1.0 - bounds [4] n = 400.0, 1.0 - bounds [5] n = 400.0, 0.0 - - -generated JSON - - - { - "id": "20.5000.1025/64ae0cf0dacb7ce30ba7", - "typeName": "ODStypeBIO-1902", - "images": { - "imageName": "hi-res", - "source": "#/payloads", - "mediaType": "image/jpg", - "imageWidth": 400, - "imageHeight": 280, - "xResolution": 0, - "yResolution": 0, - "colorSpace": "", - "iiProfileName": "", - "creator": "", - "created": "", - "project": "SDR prototype", - "license": "CC BY 4.0" - }, - "payloads": [ - "name = hi-res", - "filename = 1427463506459UAeHPJw9jXoET1sF.jfif", - "mediaType = image/jpeg", - "size n = 15063" - ], - "regions": [ - { - "name": "label", - "bounds": [ - [100.0, 0.0], - [101.0, 0.0], - [101.0, 1.0], - [100.0, 1.0], - [100.0, 0.0] - ] - }, - { - "name": "barcode", - "bounds": [ - [400.0, 0.0], - [401.0, 0.0], - [401.0, 1.0], - [400.0, 1.0], - [400.0, 0.0] - ] - } - ] -} - - - - ->>Now using composite pattern for the regions - - -id = 20.5000.1025/64ae0cf0dacb7ce30ba7 -typeName = ODStypeBIO-1902 -images - imageName = 7870917_5bb2274d436ebab560cb85b83ba21d89fa8bc065 - source = https://example.org/7870917_5bb2274d436ebab560cb85b83ba21d89fa8bc065.jpg - mediaType = image/jpg - imageWidth n = 8688 - imageHeight n = 5792 - xResolution n = 1450 - yResolution n = 965 - colorSpace n = 1 - iccProfileName = - creator = NHM Digitisation Team - created = 2019-07-11T15:37:48.000Z - project = SDR prototype - license = CC BY 4.0 -payloads [] = name = thumbnail, filename = 1427463506459UAeHPJw9jXoET1sF.jfif, mediaType = image/jpeg, size n = 15063 -regions[0] - name = labelRegion - bounds [1] n = 600.0, 4.0 - bounds [2] n = 900.0, 4.0 - bounds [3] n = 900.0, 9.0 - bounds [4] n = 600.0, 9.0 - bounds [5] n = 600.0, 4.0 - regions[0] - name = textlineRegion - bounds [1] n = 600.0, 5.0 - bounds [2] n = 900.0, 5.0 - bounds [3] n = 900.0, 6.0 - bounds [4] n = 600.0, 6.0 - bounds [5] n = 600.0, 5.0 - regions[1] - name = textlineRegion - bounds [1] n = 600.0, 6.0 - bounds [2] n = 900.0, 6.0 - bounds [3] n = 900.0, 7.0 - bounds [4] n = 600.0, 7.0 - bounds [5] n = 600.0, 6.0 - regions[2] - name = textlineRegion - bounds [1] n = 600.0, 7.0 - bounds [2] n = 900.0, 7.0 - bounds [3] n = 900.0, 8.0 - bounds [4] n = 600.0, 8.0 - bounds [5] n = 600.0, 7.0 - regions[3] - name = textlineRegion - bounds [1] n = 600.0, 8.0 - bounds [2] n = 900.0, 8.0 - bounds [3] n = 900.0, 9.0 - bounds [4] n = 600.0, 9.0 - bounds [5] n = 600.0, 8.0 -regions[1] - name = barcodeRegion - bounds [1] n = 600.0, 1.0 - bounds [2] n = 900.0, 1.0 - bounds [3] n = 900.0, 3.0 - bounds [4] n = 600.0, 3.0 - bounds [5] n = 600.0, 1.0 - - -JSON generated > - -```json - -{ - "id": "20.5000.1025/64ae0cf0dacb7ce30ba7", - "typeName": "ODStypeBIO-1902", - "images": { - "imageName": "7870917_5bb2274d436ebab560cb85b83ba21d89fa8bc065", - "source": "https://example.org/7870917_5bb2274d436ebab560cb85b83ba21d89fa8bc065.jpg", - "mediaType": "image/jpg", - "imageWidth": 8688, - "imageHeight": 5792, - "xResolution": 1450, - "yResolution": 965, - "colorSpace": 1, - "iccProfileName": "", - "creator": "NHM Digitisation Team", - "created": "2019-07-11T15:37:48.000Z", - "project": "SDR prototype", - "license": "CC BY 4.0" - }, - "payloads": [ - "name = thumbnail", - "filename = 1427463506459UAeHPJw9jXoET1sF.jfif", - "mediaType = image/jpeg", - "size n = 15063" - ], - "regions": [ - { - "name": "labelRegion", - "bounds": [ - [600, 4], - [900, 4], - [900, 9], - [600, 9], - [600, 4] - ], - "regions": [ - { - "name": "textlineRegion", - "bounds": [ - [600, 5], - [900, 5], - [900, 6], - [600, 6], - [600, 5] - ] - }, - { - "name": "textlineRegion", - "bounds": [ - [600, 6], - [900, 6], - [900, 7], - [600, 7], - [600, 6] - ] - }, - { - "name": "textlineRegion", - "bounds": [ - [600, 7], - [900, 7], - [900, 8], - [600, 8], - [600, 7] - ] - }, - { - "name": "textlineRegion", - "bounds": [ - [600, 8], - [900, 8], - [900, 9], - [600, 9], - [600, 8] - ] - } - ] - }, - { - "name": "barcodeRegion", - "bounds": [ - [600, 1], - [900, 1], - [900, 3], - [600, 3], - [600, 1] - ] - } - ] -} diff --git a/oldcontent/json-examples-and-schemas/basic-image-object/openDS-bio-schema.json b/oldcontent/json-examples-and-schemas/basic-image-object/openDS-bio-schema.json deleted file mode 100644 index e69de29..0000000 diff --git a/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example1.md b/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example1.md deleted file mode 100644 index fa3a238..0000000 --- a/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example1.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -# Structure of openDS json schemas ---- - -## Introduction -Using examples, this page explains the structure of an [open Digital Specimen](https://github.com/DiSSCo/openDS) and declares the [JSON schema](https://json-schema.org/) to support those. - -In this form it serves as a basis for discussion and understanding. - -Important starting points for understanding are the following: - -- The structure of an openDS corresponds to the Minimum Information about a Digital Specimen (MIDS), level by level. -- The definition of an openDS here corresponds to the Digital Specimen class in the [object model](https://github.com/DiSSCo/openDS/blob/master/data-model/data-model-intro.md). - -## Example 1: MIDS level 1, authoritative information only -An example DS for a physical specimen in the collection of the Muséum National d'Histoire Naturelle, Paris (MNHN) with the identifier "MNHN-IM-2013-8488"; compliant with MIDS level 1 and having no images or supplementary information. - -Source of data: https://science.mnhn.fr/institution/mnhn/collection/im/item/2013-8488 - -Location of DS: https://nsidr.org/objects/20.5000.1025/64ae0cf0dacb7bd20ba5?pretty - -```json -{ - "id": "20.5000.1025/64ae0cf0dacb7bd20ba5", - "typeName": "ODStype1802", - "authoritative": { - "modified": "2021-02-22T14:10:20.824Z", - "midsLevel": 1, - "physicalSpecimenId": "MNHN-IM-2013-8488", - "institution": [ - "Code (GRSciColl)": "MNHN", - "Referent": "https://ror.org/03wkt5x30" - ], - "materialType": "Alcohol, 95%", - "name": "Pygmaepterys pointieri Garrigues & Merle, 2014" - } -} -``` - -To explain this JSON fragment, -- The `id` is the persistent identifier of the DS. We use 20.5000.1025/*\_suffix\_* for the examples here, where the *\_suffix\_* is randomly generated by the repository server where this DS object is first created. -- The `typeName` is the formal name given to the definition of this specific structure for a DS. The `typeName` "ODStype1802" means this JSON fragment is of '*open digital specimen type*' with a version identity '*1802*'. This `typeName` corresponds to the name of the JSON Schema against which this JSON fragment was constructed, and against which it can be parsed/verified. The schema is given below. -- The next part `authoritative: { ... }` is the authoritative a_section with content corresponding to what we expect to see at [MIDS level 1](https://github.com/tdwg/mids/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc+label%3A%22MIDS+Element%22+label%3AMIDS-1) i.e., the following six information elements, each with one or more values. - -## Structure of the schema for the above example -The JSON schema for the above example begins with the definition of the schema itself - the first five lines of the JSON fragment below. It states the version of the [JSON schema specification](https://json-schema.org/) that applies and gives an identifier, description, type and title to the schema definition. - -```json -{ - "$schema": "http://json-schema.org/draft/2019-09/schema#", - "$id": "https://nsidr.org/schemas/opendsschema.json", - "description": "v0.4, 22 February 2021. JSON schema for an open Digital Specimen.", - "type": "object", - "title": "ODStype1802", - "properties": { - "id": { "type": "string" }, - "typeName": { "type": "string", "const": [ "ODStype1802" ] }, - "authoritative": { - "$id": "#/properties/a_section", - "type": "object", - "properties": { - "$comment": "authoritative properties here; list mandatory ones as required (below)" - }, - "required": [ ] - }, - "$comment": " ... several more optional sections of the schema appear here, see below ... " - }, - "required": [ "id", "typeName", "authoritative" ] -} -``` - -The schema then specifies as its properties what is being defined i.e., an object of type "ODStype1802" with its included subsets of specimen related properties. The first subset of specimen related properties - the authoritative properties - appears next. At the end of the authoritative (a_section) a list of those property keys that are mandatory in that section appears as the `required` validation array. This `required` array is empty in the fragment above and will be filled in later on below. The ODS object's `id`, `typeName` and `authoritative` section are all required for an open Digital Specimen to be a valid construct. So, this is the minimum viable construct for an open Digital Specimen. The ODS object's `id` must be a valid Handle. This constraint still needs to be added to the schema fragment. - -*Notes to self about the fragment above:* - -- *We need to constrain the `id` to be a valid Handle. How to do that?* -- *do we need to pull in the $context here? Unresolved issue as to how we exploit links to semantics* -- *the ODSType1802 schema is deployed at http://nsidr.org/#objects/20.5000.1025/af08540a7a96066fdf23.* -- *the json description of the DTR ***type definition*** of an openDS is different from this schema definition. Logically they will be the same but how they are used is different.* -- *how do we process type definitions? What general purspose software exists for dealing with them? Out of date now, but gives some hints: https://dlib.org/dlib/may07/saidis/05saidis.html.* -- *The schema references the current draft 2019-09 of the JSON-schema specification. However, some schema validator tools work only with earlier versions. e.g., the https://extendsclass.com/json-schema-validator.html works with /draft-07/schema#.* -- *Consider that we might want to enforce a convention (pattern) for any specific propertyNames that are not already in the schema but which might be added to a JSON instance.* -- *Consider that we might want to use the additionalProperties keyword to control how the extensions (E) section works.* - -## Overall structure (sections of the schema) -At the highest level of structure, the properties of an open Digital Specimen are divided into several sections, each represented in the schema as a nested JSON object. We've already been introduced to the first of these, the authoritative or a_section. It together with the other section types are explained as follows: - -- **authoritative a_section**, contains essential data about a specimen. The a_section is represented by an a_section object containing all the key/value pair properties that are deemed to be authoritative information about a physical specimen. The complete schema definition of the a_section corresponds to the information elements expected to be present at MIDS level 2. The a_section is mandatory. - -- **images i_section**, containing references to images or images themselves of the specimen and/or its labels. The images section is represented by an i_section object containing metadata about the available images. - -- **supplementary s_section**, containing links to supplementary data derived from a specimen. The supplementary section is represented by an s_section object, which itself may contain multiple objects grouping specific kinds of supplementary information (such as external links) together. The definition of the s_section corresponds to the additional information elements expected to be present at MIDS level 3 and more. - -- **tertiary t_section**, containing links to related data associated with a specimen but not directly derived from the physical specimen. - -Expanding on the basic schema construct above, the JSON schema fragment describing this overall structure is the following: - -```json -{ - "$schema": "http://json-schema.org/draft/2019-09/schema#", - "$id": "https://nsidr.org/schemas/opendsschema.json", - "description": "v0.4, 22 February 2021. JSON schema for an open Digital Specimen.", - "type": "object", - "title": "ODStype1802", - "properties": { - "id": { "type": "string" }, - "typeName": { "type": "string", "const": [ "ODStype1802" ] }, - "authoritative": { - "$id": "#/properties/a_section", - "type": "object", - "properties": { - "$comment": "authoritative properties here; list mandatory ones as required (below)" - }, - "required": [ ] - }, - "images": { - "$id": "#/properties/i_section", - "type": "object", - "properties": { - "$comment": "image properties here; list mandatory ones as required (below)" - }, - "required": [ ] - }, - "supplementary": { - "$id": "#/properties/s_section", - "type": "object", - "properties": { - "$comment": "supplementary properties here; list mandatory ones as required (below)" - }, - "required": [ ] - }, - "tertiary": { - "$id": "#/properties/t_section", - "type": "object", - "properties": { - "$comment": "tertiary properties here; list mandatory ones as required (below)" - }, - "required": [ ] - }, - "$comment": " ... further optional sections of the schema can appear here ... " - }, - "required": [ "id", "typeName", "authoritative" ] -} -``` - -### Other section types -*For further study.* - -There are several additional section types for further study, including: - -- **extension e_section**, *for further study. This is likely to be proprietary to specific organisations/systems.* - -- **operations/methods o_section**, *for further study.* - -- **payloads (contents) p_section**, *for further study.* *thumbnail images perhaps?* - -- ***Others ...*** - -## Authoritative (a_section) information elements -The information element content of the authoritative section aligns with the [Minimum Information about a Digital Specimen (MIDS)](https://github.com/tdwg/mids/blob/main/MIDS-definition.md) that we expect to see i.e., information at one of the MIDS levels 0 - 3. The simplest example, [example 1 above](#example-1-mids-level-1-authoritative-information-only) helps us to understand the structure of the a_section schema. It contains six information elements. Definitions of each of these are given in the table below. Each is basically a key/value pair definition. That for the `institution` element is a little more complex, as it consists of two parts. - -| **Info element** | **Definition** | -| --- | --- | -| modified | Date-time. Refer to [MIDS Information - Modified](https://github.com/tdwg/mids/issues/8) | -| midsLevel| Integer value, range 0-3. | -| physicalSpecimenId | Physical specimen identifier. Refer to [MIDS Information - PhysicalSpecimenId](https://github.com/tdwg/mids/issues/10) | -| institution | Refer to [MIDS Information - Institution](https://github.com/tdwg/mids/issues/11) | -| materialType | Refer to [MIDS Information - MaterialType](https://github.com/tdwg/mids/issues/14) | -| name | Refer to [MIDS Information - Name](https://github.com/tdwg/mids/issues/12) | - -### JSON fragment for a_section -Here is the JSON fragment for the a_section property definitions above. - -```json - "authoritative": { - "$id": "#/properties/a_section", - "type": "object", - "properties": { - "modified": { "type": "string", "title": "Modified (date:time)", "format": "date-time" }, - "midsLevel": { "type": "integer", "minimum": 0, "maximum": 3 }, - "physicalSpecimenId": { "type": "string", "title": "Physical specimen identifier" }, - "institution": { - "type": "array", "items": [ {"type": "string", "title": "Code (GRSciColl)" }, - {"type": "string", "format": "uri", "title": "Referent" } ] - }, - "materialType": { "type": "string", "title": "Material type" }, - "name": { "type": "string", "maxLength": 128, "title": "Name" } - }, - "required": [ "modified", "midsLevel", "physicalSpecimenId", "institution", "materialType", "name" ] - } -``` -### Minimum required -Together with `id` and `title` (above) only a very small number of information elements are mandatory for an open digital specimen to come into existence (i.e., to be created). The first of these is `midsLevel`, which is a declared or calculated value of the present MIDS Level reached by the available specimen data. Also required are the information elements `modified`, `physicalSpecimenId` and `institution`. These correspond to the information elements required at [MIDS level 0](https://github.com/tdwg/mids/issues?q=is%3Aopen+is%3Aissue+label%3AMIDS-0+label%3A%22MIDS+Element%22) according to the [TDWG MIDS definition](https://github.com/tdwg/mids/blob/main/MIDS-definition.md). Thus, these are specified as needed in the `required` array for the a_section. Because this schema corresponds to the [example 1 above](#example-1-mids-level-1-authoritative-information-only), we also include `materialType` and `name` as being required. - -### Other a_section properties: conditional subschemas for different values of midsLevel -At the present time (25Feb2021) and based on the example, only the MIDS-0 and MIDS-1 properties have been defined. Others, for MIDS levels 2 and 3 will be added later. This leads to the need for conditional subschemas for different values of midsLevel. - -Depending on the declared MIDS level, we'd expect to see a certain set of properties present in the ODS. We can apply subschemas conditionally, using If-Then-Else constructs. - -*Note to self: Need to look at subschemas and how to structure these as separate schema fragments / type definitions i.e., the type definition of an ODS a_section will be different depending on the declared/calculated MIDSLevel.* - -To implement this, something along the following lines is likely. This example distinguishes between what is required at MIDS-0 and MIDS-1. It would be more complext when we add additional constructions for MIDS-2 and MIDS-3. It still needs to checked, tested and optimised. Of course, it would be better that key definitions only appear once to reduce the possibility of introducing errors when changes are made. - -```json - "authoritative": { - "$id": "#/properties/a_section", - "type": "object", - "properties": { - "modified": { "type": "string", "title": "Modified (date:time)", "format": "date-time" }, - "midsLevel": { "type": "integer", "minimum": 0, "maximum": 3 }, - }, - "if": { "properties": { "midsLevel": { "const": 0 } }, - "then": { "properties": { - "$comment": "MIDS-0 elements", - "physicalSpecimenId": { "type": "string", "title": "Physical specimen identifier" }, - "institution": { "type": "array", "items": [ {"type": "string", "title": "Code (GRSciColl)" }, {"type": "string", "title": "Referent" } ] - }, - "required": [ "physicalSpecimenId", "institution" ] }, - }, - "else": { "properties": { - "$comment": "MIDS-1 elements", - "physicalSpecimenId": { "type": "string", "title": "Physical specimen identifier" }, - "institution": { "type": "array", "items": [ {"type": "string", "title": "Code (GRSciColl)" }, {"type": "string", "title": "Referent" } ] - }, - "materialType": {}, - "name": { "type": "string", "maxLength": 128, "title": "Name" } - }, - "required": [ "physicalSpecimenId", "institution", "materialType", "name" ] - }, - "required": [ "modified", "midsLevel" ] }, - } - } -``` - -## Image i_section information elements -*To be completed.* - -To do: -- SDR requires a data object for describing labelled regions (ROIs) on an image. IIIF now supports polygon region descriptions, and will be used internally for image data. -- Image section must contain description of regions of interest for each image. https://www.loc.gov/standards/alto/ instead of iiif. - -## Supplementary s_section information elements -Definitions of individual information elements belonging to the supplementary s_section follow. Each definition is a key/value pair. - -*To be completed. The schema fragment below is just an illustration/placeholder.* - -```json - "supplementary": { - "$id": "#/properties/s_section", - "type": "object", - "properties": { - "externalLinks": { - "type": "array", - "items": { - "type": "string", - - }, - } - } - } - } -``` -## Complete JSON schema for validation testing -Putting the schema fragments together for [example 1 above](#example-1-mids-level-1-authoritative-information-only) we obtain the following schema for validation. - -```json -{ - "$schema": "http://json-schema.org/draft/2019-09/schema#", - "$id": "https://nsidr.org/schemas/opendsschema.json", - "description": "v0.4, 22 February 2021. JSON schema for an open Digital Specimen.", - "type": "object", - "title": "ODStype1802", - "properties": { - "id": { "type": "string" }, - "typeName": { "type": "string", "const": [ "ODStype1802" ] }, - "authoritative": { - "$id": "#/properties/a_section", - "type": "object", - "properties": { - "modified": { "type": "string", "title": "Modified (date:time)", "format": "date-time" }, - "midsLevel": { "type": "integer", "minimum": 0, "maximum": 3 }, - "physicalSpecimenId": { "type": "string", "title": "Physical specimen identifier" }, - "institution": { - "type": "array", "items": [ {"type": "string", "title": "Code (GRSciColl)" }, - {"type": "string", "format": "uri", "title": "Referent" } ] - }, - "materialType": { "type": "string", "title": "Material type" }, - "name": { "type": "string", "maxLength": 128, "title": "Name" } - }, - "required": [ "modified", "midsLevel", "physicalSpecimenId", "institution", "materialType", "name" ] - }, - "required": [ "id", "typeName", "authoritative" ] -} -``` - -*Notes to self, 25/02/2021:* -- *Note, deployed (adapted) into nsidr.org as schema ODStype1802 on 18th February 2021.* -- *Institution array is open-ended, allowing as many items as you like to be added. In CORDRA How do I allow additional referents to be added as format=uri rather than just as uncontrolled strings? Within an array, is it possible in the schema to constrain the number of elements and their order?* -- *Material Type is not fully specified yet. Needs a controlled vocabulary At the moment in CORDRA, just a string type.* - - -END. - - - diff --git a/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example2.md b/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example2.md deleted file mode 100644 index 0767b35..0000000 --- a/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example2.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -# Basic json - example 2 ---- - -## Introduction -Continuing from the [JSON for example 1 and its corresponding schema](basic-json-schema.md), let's add some images. - -## Example 2: MIDS level 1, authoritative information and available images - -If we look at the [source of the data](https://science.mnhn.fr/institution/mnhn/collection/im/item/2013-8488) we can find there are two images available: -- a low resolution image: http://imager.mnhn.fr/imager3/w400/media/1427463506459UAeHPJw9jXoET1sF -- a higher resolution image: http://mediaphoto.mnhn.fr/media/1427463506459UAeHPJw9jXoET1sF - -Inspecting the image files with a suitable [Exif metadata viewer](https://exifinfo.org/), we discover the format is [JFIF](https://fileinfo.com/extension/jfif), a JPEG variation intended to allow easy exchange of images across platforms and to provide additional useful metadata not provided for by the base JPEG standard. The low res image has very little information given about it - just an indication of size (400 x 280) pixels with no resolution information. It's a 'thumbnail' image that displays on a standard computer screen with a resolution of 72dpi. For the high res image, considerably more information is [available](https://exifinfo.org/detail/UAO-L0dx_KQM5DDMXxKv8w). The image is 3780 x 2646 pixels at a resolution of 300dpi in each of the X and Y directions. It uses standard RGB colour representation with a specified standard International Colour Consortium (ICC) colour profile for rendering/printing on specialist display/printer devices. The image was created on March 27th, 2015. - -A machine could deduce the above details by examining the files directly, for example using the [EXifTool Perl library](https://exiftool.org/). Even so, there is little information provided that would allow a user to deduce where the image had come from, who made it or why. A human can read from the [webpage](https://science.mnhn.fr/institution/mnhn/collection/im/item/2013-8488) that the image was created in 2015 by Manuel Caballer as part of the French e-ReColNat project, and that it is licensed as [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). This is information about the image but it is part of the webpage for the specimen and not part of the image metadata itself. Nevertheless, from the openDS perspective this is useful information to include with the image. - -For the present example, we'll assume we want to include the following as the specimen image information: - -- the thumbnail image itself, with its pixel dimensions so people can immediately see a picture of the specimen; -- the location of the high resolution image, such that it can be retrieved for further use by someone interested in the specimen; -- the metadata about the high res image i.e., pixel dimensions, resolution, colour profile, creation date, name of the person creating the image, the project producing it and licensing details. - -From the JSON perspective, this indicates we need to provide for an array of one or more image objects. We can extend our earlier [example 1](basic-json-schema.md) as follows below with an images (i_) section that contains an array of image objects. Since, in the general case we don't know how many images can be associated with a specimen we do not name the objects within the JSON `availableImages` array. - ->>Update this uri once we've put the example into nsidr.org -Location of DS: https://nsidr.org/objects/20.5000.1025/64ae0cf0dacb7bd20ba5?pretty - -```json -{ - "id": "20.5000.1025/64ae0cf0dacb7bd20ba5", - "typeName": "ODStype1802", - "authoritative": { - "modified": "2021-02-22T14:10:20.824Z", - "midsLevel": 1, - "physicalSpecimenId": "MNHN-IM-2013-8488", - "institution": [ - "MNHN", - "https://ror.org/03wkt5x30" - ], - "materialType": "Alcohol, 95%", - "name": "Pygmaepterys pointieri Garrigues & Merle, 2014" - }, - "images": { - "availableImages": [ - { - "imageName": "thumbnail", - "source": "#/payloads", - "mediaType": "image/jpeg", - "imageWidth": "400", - "imageHeight": "280", - "xResolution": "", - "yResolution": "", - "colorSpace": "", - "iccProfileName": "", - "creator": "", - "created": "", - "project": "", - "license": "CC BY 4.0" - }, - { - "imageName": "hi-res", - "source": "http://mediaphoto.mnhn.fr/media/1427463506459UAeHPJw9jXoET1sF", - "mediaType": "image/jpeg", - "imageWidth": "3780", - "imageHeight": "2646", - "xResolution": "300", - "yResolution": "300", - "colorSpace": "sRGB", - "iccProfileName": "sRGB IEC61966-2.1", - "creator": "Manuel Caballer", - "created": "2015:03:27T14:33:02Z", - "project": "e-ReColNat", - "license": "CC BY 4.0" - } - ] - }, - "payloads": [ - { - "name": "thumbnail", - "filename": "1427463506459UAeHPJw9jXoET1sF.jfif", - "mediaType": "image/jpeg", - "size": 15063 - } - ] -} -``` - -# Validation -There are several JSON validators available online we can use to work with this JSON fragment. - -## Simple validators and formatters -Simple validators and/or formatters can tell us the fragment is syntactically correct and reveal the structure of complex fragments. Some offer transformation between JSON and other representations such as XML and CSV. Here are a few to try: -- [JSONLint validator](https://jsonlint.com/) -- [jsonformatter.org](https://jsonformatter.org/) -- [curiousconcept.com](https://jsonformatter.curiousconcept.com/#) - -## Validating against a schema -More interesting and useful is these tools that validate a JSON fragment against a JSON schema supplied by the user: -- [jsonschemavalidator.net](https://www.jsonschemavalidator.net/) -- [with common java json tools](https://json-schema-validator.herokuapp.com/) -- [jsonschemalint](https://jsonschemalint.com/) - -## Generating schemas -Generating JSON schemas is a time-consuming and error-prone process when done by hand. The best approach is to automatically generate a schema from an example JSON fragment and then to optimise by hand. - -Several automatic JSON schema generators are available online, with varying capabilities. Some generate just a bare minimum schema whilst others generate more comprehensive, more descriptive schemas that include example codings as well. These tend to be more verbose but easier to comprehend and optimise by hand. -- [jsonschema.net](https://www.jsonschema.net/home) - looks a good one because it allows editing of the JSON and the schema side by side. It has a graph visualization of the schema as well too. However, it doesn't appear to support the draft/2019-09/schema, only supporing upto draft-07. Having said that, there is an [open GitHub issue](https://github.com/jackwootton/json-schema/issues/86) for that. -- [extendsclass](https://extendsclass.com/json-schema-validator.html) makes use of the widely used [Ajv validator](https://ajv.js.org/) and allows to generate schemas from fragments and vice versa. Ajv has the added benefit of being capable of generating code to turn Schemas into JavaScript validation functions that can be bundled as part of applications. - -The main differences between these two generators are that the first places a complete example at the beginning of the schema whereas the latter breaks the example up into multiple short examples, each at its own place in the schema. The first includes a $description for each property (thus more documenting), whereas the latter doesn't include this (although it can be added by hand). - -- [liquid-technologies](https://www.liquid-technologies.com/online-json-to-schema-converter) - has tools for both directions i.e., JSON -> JSON schema, and vive-versa. -- [quicktype](https://quicktype.io/) - -## Schema(s) - What do we need? - -- a schema that can be used to generate (by a producer) and validate (by a consumer) an open Digital Specimen as it is communicated from one system to another. -- a CORDRA schema that can be used internally within CORDRA for storing open Digital Specimens. This schema will be similar to the above one, but contains more details specific to the CORDRA implementation, such as what to preview in search results, etc. - -- type definitions into a type registry that ODS can be produced/validated/stored against in an object repository/server such as CORDRA. - - -So, what should be the workflow for preparing these schemas? -1. Prepare an exemplar JSON fragment, similar to above containing required structures, K/V pairs, etc. -2. Use an appropriate generator tool to auto-generate a JSON schema for the fragment. -3. From the auto-generated schema, optimise an 'ODStype schema' by hand in an iterative process until it works with (validates) a variety of JSON fragment examples, including boundary conditions. This should include producing JSON fragments against the schema in one system and consuming those fragments against the schema in another system. Note that optimisations must be kept to a minimum and a record of them must also be kept so that they can subsequently be re-applied to a newly generated schema as necessary. Note that at present for development purposes, it is the schema `title` (corresponding to `typeName` in the JSON fragment instance) that distinguishes one version/variant of the schema from another. We are using four digits beginning at '1802', thus `"title": "ODStype1802"`, `"title": "ODStype1802"`, etc. -4. Further optimise the schema to become a CORDRA (or other object server) internal schema. Ditto, a record of optimisations must be kept. -5. Derive and register type definitions into type registry - -The above implies several related artefacts to be kept under version control: -- the exemplar JSON fragment -- the auto-generated schema -- the hand-optimised ODStype schema and list of optimisations -- the CORDRA variant of the ODStype schema and list of variations from the ODStype schema -- the type definitions - -How to make this error-proof as possible? - - -The schema example in [example2-schema.json](example2-schema.json) has been generated with the [quicktype](https://quicktype.io/) tool. - -Got to here>>The next step might to take this schema and insert some examples and defaults into it and see if we can use extendclass tool to recreate the JSON example from it, paying attention to how it deals with the two alternative sources for images - a file in the payload or a uri. -Also, apply some of the schema customisations from below. - - -# More real example from MeiseBG -Have a look at this prov example, which illustrates how massive it can grow when many people perform activities on an entity! https://api.gbif-uat.org/v1/occurrence/2840596485/fragment -https://cite.research-software.org/ - -See Claus's email of 14th April on validation in python. - -To do: -- SDR requires a data object for describing labelled regions (ROIs) on an image. IIIF now supports polygon region descriptions, and will be used internally for image data. -- Image section must contain description of regions of interest for each image. https://www.loc.gov/standards/alto/ instead of iiif. - - - - -## Complete JSON schema for validation testing -To be completed. - - -END. - - - diff --git a/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example3.md b/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example3.md deleted file mode 100644 index 31607e3..0000000 --- a/oldcontent/json-examples-and-schemas/digital-specimen-object/basic-json-example3.md +++ /dev/null @@ -1,837 +0,0 @@ ---- -# Basic json - example 3 ---- - -## Introduction -Continuing from [example 2](basic-json-example2.md), let's take a [real example from NHMUK](https://data.nhm.ac.uk/object/893e0b8c-9dab-40b5-872b-51f08a69e765/1620691200000) and see what we can do to change that into a Digital Specimen object with semantics. - -## Example 3: NHMUK010517563, *Elophila nymphaeata* (Linnaeus, 1758) - -### Step 1: Basic ODS, as per example 1. -First, let's make an object that's equivalent to the simple example 1 object. - -This will store in nsidr.org with the type schema specified by the `typeName`. You can find it by searching nsidr.org directly, or by resolving the `id` value using, for example the https://doi.org resolver. - -
- Click to see JSON for example 3 - -```json -{ - "id": "20.5000.1025/ae88bb3a666ec72dbc51", - "typeName": "ODStype1802", - "authoritative": { - "modified": "2021-06-17T09:18:02.130Z", - "midsLevel": 1, - "physicalSpecimenId": "NHMUK010517563", - "institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "materialType": "Dry - pinned", - "name": "Elophila nymphaeata (Linnaeus, 1758)" - } -} -``` -
- -### Step 2: Basic semantic ODS -Let's turn this object into a semantically meaningful ODS by adding JSON-LD `@context`, `@graph` and `@id` elements. - -
- Click to see JSON for the basic semantic ODS. - -```json -{ - "id": "20.5000.1025/ae88bb3a666ec72dbc52", - "typeName": "ODStype1802", - "@context": { - "ods": "http://github.com/hardistyar/openDS/ods-ontology/terms/" - }, - "@graph": [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ] -} -``` - -
- -This is valid JSON-LD and it saves in nsidr.org as a valid object of type ODStype1802. I've given it a slightly different Handle suffix to distinguish it from the previous object. Notice several things: - -- The JSON-LD `@id` node identifier is derived from and matches the object `id`, making this object machine-readable by Semantic Web tools. Note that by using a URI that points to a proxy for a Handle resolver, we've introduced a level of indirection that removes the location dependence typically associated with URIs. We know that we can always find this object via its `id` and a resolver of our choice. We could have pointed to the actual resource at the place where it is located (stored) by setting the `@id` node identifier to the URL https://nsidr.org/#objects/20.5000.1025/ae88bb3a666ec72dbc52. -- This object isn't semantically useful yet because the ods: terms referenced by the `@context` node are not defined anywhere. The IRI is just a placeholder. However, what we have achieved is to embed semantic assertions into a digital object. (Note: Whether or not this DO is a FAIR DO is still an open question. We need to check the extent to which it meets the requirements of the draft FDO Core Specification / FDO Framework). -- In nsidr.org, apart from the `modified` field which is autogenerated by Cordra anyway, none of the fields the type schema expects are filled . It doesn't recognise what I've given as corresponding to the schema but at the moment we're not prohibiting nsidr from storing any valid JSON. This means we need a new schema (type) for this object if we want to control its content with `required` properties. - -### Step 3: Autogenerate a JSON schema -Let's now autogenerate a JSON schema to validate the object we have. - -First question is which version of the JSON Schema standard do we want to work with? We don't think Cordra is fully up to date with recent specification drafts, being dependent on the V4 library. - -This schema is autogenerated at https://www.jsonschema.net/home. It includes our complete example object at the beginning, as well as providing parts of that example all the way through. It provides `description` elements allowing us to be clear and specific about what each property is, and `default` elements allowing us to set default values to be used when no value is provided during object creation. - -
- Click to see the auto-generated JSON schema. - -```json -{ - "$schema": "http://json-schema.org/draft-07/schema", - "$id": "http://example.com/example.json", - "type": "object", - "title": "The root schema", - "description": "The root schema comprises the entire JSON document.", - "default": {}, - "examples": [ - { - "id": "20.5000.1025/ae88bb3a666ec72dbc52", - "typeName": "ODStype1802", - "@context": { - "ods": "http://github.com/hardistyar/openDS/terms/" - }, - "@graph": [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ] - } - ], - "required": [ - "id", - "typeName", - "@context", - "@graph" - ], - "properties": { - "id": { - "$id": "#/properties/id", - "type": "string", - "title": "The id schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "20.5000.1025/ae88bb3a666ec72dbc52" - ] - }, - "typeName": { - "$id": "#/properties/typeName", - "type": "string", - "title": "The typeName schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "ODStype1802" - ] - }, - "@context": { - "$id": "#/properties/%40context", - "type": "object", - "title": "The @context schema", - "description": "An explanation about the purpose of this instance.", - "default": {}, - "examples": [ - { - "ods": "http://github.com/hardistyar/openDS/terms/" - } - ], - "required": [ - "ods" - ], - "properties": { - "ods": { - "$id": "#/properties/%40context/properties/ods", - "type": "string", - "title": "The ods schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "http://github.com/hardistyar/openDS/terms/" - ] - } - }, - "additionalProperties": true - }, - "@graph": { - "$id": "#/properties/%40graph", - "type": "array", - "title": "The @graph schema", - "description": "An explanation about the purpose of this instance.", - "default": [], - "examples": [ - [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ] - ], - "additionalItems": true, - "items": { - "$id": "#/properties/%40graph/items", - "anyOf": [ - { - "$id": "#/properties/%40graph/items/anyOf/0", - "type": "object", - "title": "The first anyOf schema", - "description": "An explanation about the purpose of this instance.", - "default": {}, - "examples": [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ], - "required": [ - "@id", - "ods:authoritative" - ], - "properties": { - "@id": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/%40id", - "type": "string", - "title": "The @id schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52" - ] - }, - "ods:authoritative": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative", - "type": "object", - "title": "The ods:authoritative schema", - "description": "An explanation about the purpose of this instance.", - "default": {}, - "examples": [ - { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - ], - "required": [ - "ods:modified", - "ods:midsLevel", - "ods:physicalSpecimenId", - "ods:institution", - "ods:materialType", - "ods:name" - ], - "properties": { - "ods:modified": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Amodified", - "type": "string", - "title": "The ods:modified schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "2021-06-17T09:18:02.130Z" - ] - }, - "ods:midsLevel": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3AmidsLevel", - "type": "integer", - "title": "The ods:midsLevel schema", - "description": "An explanation about the purpose of this instance.", - "default": 0, - "examples": [ - 1 - ] - }, - "ods:physicalSpecimenId": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3AphysicalSpecimenId", - "type": "string", - "title": "The ods:physicalSpecimenId schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "NHMUK010517563" - ] - }, - "ods:institution": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Ainstitution", - "type": "array", - "title": "The ods:institution schema", - "description": "An explanation about the purpose of this instance.", - "default": [], - "examples": [ - [ - "NHMUK", - "https://ror.org/039zvsn29" - ] - ], - "additionalItems": true, - "items": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Ainstitution/items", - "anyOf": [ - { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Ainstitution/items/anyOf/0", - "type": "string", - "title": "The first anyOf schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "NHMUK", - "https://ror.org/039zvsn29" - ] - } - ] - } - }, - "ods:materialType": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3AmaterialType", - "type": "string", - "title": "The ods:materialType schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "Dry - pinned" - ] - }, - "ods:name": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Aname", - "type": "string", - "title": "The ods:name schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "Elophila nymphaeata (Linnaeus, 1758)" - ] - } - }, - "additionalProperties": true - } - }, - "additionalProperties": true - } - ] - } - } - }, - "additionalProperties": true -} -``` - -
- -### Step 4: Optimise the schema to an ODStype schema -The next step is to take the autogenerated schema above and optimise it to the needs of openDS. At the very least, this involves renaming the schema and putting it into version control, which is what we do in this example. But there is probably more to it than that; to be further investigated. - -The changes we need to make are the following: - -1. The identifier of the schema, `$id` must be given a suitable URI so that it can be found. We change this to point to a location in the GitHub repository for openDS where this schema can be found. - - `"$id": "https://github.com/DiSSCo/openDS/json-examples-and-schemas/digital-specimen-object/example3-opends-schema.json",` -2. The `title` of the schema must be changed to reflect the object `typeName` that this schema applies to. At this point, it's appropriate to allocate a new `typeName` as well, so we'll set that to "ODStype1804". - - change: `"title": "The root schema",` to `"title": "root openDS schema for ODStype1804",`. - - In the `"examples"` array, change: `"typeName": "ODStype1802",` to `"typeName": "ODStype1804",`. -3. In the `"properties"` node, make the following changes: - - change example for `"typeName"` to ODSType1804, to match the earlier changes. - - replace the `"description"` of the purpose of each instance with something appropriate. (*17 June 2021: note that at this experimental stage I haven't provided any new description of the purposes of each instance. These can be added later when we've stabilised the design better. And here is where the needed changes should be listed.*). - - for `"ods:midsLevel"`, set maximum and minimum permitted values by including `"minimum": 0, "maximum": 3,` before the `"default": 0,` key. -4. For `"typeName"`, replace `"default": "",` with `"enum": [ "ODStype1804" ]` as the only permitted value for this object type definition. - -Change `title` for `ods:physicalSpecimenId` from `"title": "The ods:physicalSpecimenId schema",` to `"title": "Physical specimen identifier",`. - -Change `title` for `ods:institution` from `"title": "The ods:institution schema",` to `"title": "Code (GRSciColl)",`. - -*17 June 2021: Got to here>>: At line 710: need to do some more work there to get the referent in - is missing and needs `"title": "Referent",`. See schema at end, taken from Cordra.* - -
- Click to see JSON for the ODStype schema in JSON. - -```json - -{ - "$schema": "http://json-schema.org/draft-07/schema", - "$id": "https://github.com/DiSSCo/openDS/json-examples-and-schemas/digital-specimen-object/example3-opends-schema.json", - "type": "object", - "title": "root openDS schema for ODStype1804", - "description": "The root schema comprises the entire JSON document.", - "default": {}, - "examples": [ - { - "id": "20.5000.1025/ae88bb3a666ec72dbc52", - "typeName": "ODStype1804", - "@context": { - "ods": "http://github.com/hardistyar/openDS/terms/" - }, - "@graph": [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ] - } - ], - "required": [ - "id", - "typeName", - "@context", - "@graph" - ], - "properties": { - "id": { - "$id": "#/properties/id", - "type": "string", - "title": "The id schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "20.5000.1025/ae88bb3a666ec72dbc52" - ] - }, - "typeName": { - "$id": "#/properties/typeName", - "type": "string", - "title": "The typeName schema", - "description": "An explanation about the purpose of this instance.", - "enum": [ - "ODStype1804" - ], - "examples": [ - "ODStype1804" - ] - }, - "@context": { - "$id": "#/properties/%40context", - "type": "object", - "title": "The @context schema", - "description": "An explanation about the purpose of this instance.", - "default": {}, - "examples": [ - { - "ods": "http://github.com/hardistyar/openDS/terms/" - } - ], - "required": [ - "ods" - ], - "properties": { - "ods": { - "$id": "#/properties/%40context/properties/ods", - "type": "string", - "title": "The ods schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "http://github.com/hardistyar/openDS/terms/" - ] - } - }, - "additionalProperties": true - }, - "@graph": { - "$id": "#/properties/%40graph", - "type": "array", - "title": "The @graph schema", - "description": "An explanation about the purpose of this instance.", - "default": [], - "examples": [ - [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ] - ], - "additionalItems": true, - "items": { - "$id": "#/properties/%40graph/items", - "anyOf": [ - { - "$id": "#/properties/%40graph/items/anyOf/0", - "type": "object", - "title": "The first anyOf schema", - "description": "An explanation about the purpose of this instance.", - "default": {}, - "examples": [ - { - "@id": "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52", - "ods:authoritative": { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - } - ], - "required": [ - "@id", - "ods:authoritative" - ], - "properties": { - "@id": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/%40id", - "type": "string", - "title": "The @id schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "https://doi.org/20.5000.1025/ae88bb3a666ec72dbc52" - ] - }, - "ods:authoritative": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative", - "type": "object", - "title": "The ods:authoritative schema", - "description": "An explanation about the purpose of this instance.", - "default": {}, - "examples": [ - { - "ods:modified": "2021-06-17T09:18:02.130Z", - "ods:midsLevel": 1, - "ods:physicalSpecimenId": "NHMUK010517563", - "ods:institution": [ - "NHMUK", - "https://ror.org/039zvsn29" - ], - "ods:materialType": "Dry - pinned", - "ods:name": "Elophila nymphaeata (Linnaeus, 1758)" - } - ], - "required": [ - "ods:modified", - "ods:midsLevel", - "ods:physicalSpecimenId", - "ods:institution", - "ods:materialType", - "ods:name" - ], - "properties": { - "ods:modified": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Amodified", - "type": "string", - "title": "The ods:modified schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "2021-06-17T09:18:02.130Z" - ] - }, - "ods:midsLevel": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3AmidsLevel", - "type": "integer", - "title": "The ods:midsLevel schema", - "description": "An explanation about the purpose of this instance.", - "minimum": 0, - "maximum": 3, - "default": 0, - "examples": [ - 1 - ] - }, - "ods:physicalSpecimenId": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3AphysicalSpecimenId", - "type": "string", - "title": "Physical specimen identifier", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "NHMUK010517563" - ] - }, - "ods:institution": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Ainstitution", - "type": "array", - "title": "Code (GRSciColl)", - "description": "An explanation about the purpose of this instance.", - "default": [], - "examples": [ - [ - "NHMUK", - "https://ror.org/039zvsn29" - ] - ], - "additionalItems": true, - "items": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Ainstitution/items", - "anyOf": [ - { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Ainstitution/items/anyOf/0", - "type": "string", - "title": "The first anyOf schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "NHMUK", - "https://ror.org/039zvsn29" - ] - } - ] - } - }, - "ods:materialType": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3AmaterialType", - "type": "string", - "title": "The ods:materialType schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "Dry - pinned" - ] - }, - "ods:name": { - "$id": "#/properties/%40graph/items/anyOf/0/properties/ods%3Aauthoritative/properties/ods%3Aname", - "type": "string", - "title": "The ods:name schema", - "description": "An explanation about the purpose of this instance.", - "default": "", - "examples": [ - "Elophila nymphaeata (Linnaeus, 1758)" - ] - } - }, - "additionalProperties": true - } - }, - "additionalProperties": true - } - ] - } - } - }, - "additionalProperties": true -} - -``` - - -
- -### Step 5: Further optimise to a CORDRA schema -Next, we further optimise the openDS schema to become a CORDRA (or other object server) internal schema that we can use to store our example object against in nsidr.org. A record of these optimisations must also be kept. - -The changes we need to make are the following: - -1. The ... - - -*28th June (a cut and paste from Slack Cordra, Q&A on 17th June):* - -Me: I'm thinking about how to introduce semantics into my cordra objects. Specifically, I need to ensure that I end up with a json-ld @id node identifier IRI for the json node that is the object identified by the cordra object "id" key, and which matches it. I can achieve this if I specify the Handle suffix Cordra should use for the object id but is there a way to achieve it when I let Cordra autogenerate suffixes? -New - -Ben Hadden 2:21 PM -There is a JavaScript hook on the design object called `generateId` that you can use to generate your ids in any way you like. https://www.cordra.org/documentation/design/javascript-lifecycle-hooks.html. Perhaps that could meet this requirement. - -schneck 4:29 PM -Perhaps `"autoGeneratedField": "handle"` is relevant? https://www.cordra.org/documentation/design/schemas.html#type-autogeneratedfield -If you can't use just the handle, you could consider minting the handle (randomly, using an algorithm equivalent to the built-in Cordra one if you like) in beforeSchemaValidation, and setting it into both the CordraObject "id" and (with whatever additions needed) "@id" inside the CordraObject content. (A theoretical issue with this approach is the possibility of two simultaneous creations trying to use the same randomly generated id; one will fail with a possibly confusing error message.) - -*.end of paste.* - - - - - - - -
- Click to see JSON for the CORDRA schema in JSON. - -```json - - -``` - -
- -### Step 6: Derive and register type definitions into type registry -Finally, we would need to derive and register type definitions into a type registry such as the [ePIC experimental type registry](http://dtr-test.pidconsortium.eu/#) but we don't go that far with this example. - ---- - -## Relevant files for this example - -- example3-plainjson-object.json -- example3-jsonld-object.json -- example3-auto-schema.json -- example3-opends-schema.json -- example3-cordra-schema.json - -END. - - - -{ - "definitions": { - "previewInResultsTrue": { - "cordra": { - "preview": { - "showInPreview": true - } - } - }, - "previewInResultsFalse": { - "cordra": { - "preview": { - "showInPreview": false - } - } - } - }, - "$schema": "http://json-schema.org/draft/2019-09/schema#", - "$id": "https://nsidr.org/schemas/opendsschema.json", - "type": "object", - "title": "ODStype1802", - "properties": { - "id": { - "type": "string", - "cordra": { - "type": { - "autoGeneratedField": "handle", - "prependHandleMintingConfigPrefix": true - }, - "preview": { - "showInPreview": true - } - } - }, - "typeName": { - "type": "string", - "enum": [ - "ODStype1802" - ] - }, - "authoritative": { - "$id": "#/properties/a_section", - "type": "object", - "properties": { - "modified": { - "type": "string", - "cordra": { - "type": { - "autoGeneratedField": "modificationDate" - } - } - }, - "midsLevel": { - "type": "integer", - "minimum": 0, - "maximum": 3 - }, - "physicalSpecimenId": { - "type": "string", - "title": "Physical specimen identifier", - "$ref": "#/definitions/previewInResultsFalse" - }, - "institution": { - "type": "array", - "items": [ - { - "type": "string", - "title": "Code (GRSciColl)", - "$ref": "#/definitions/previewInResultsTrue" - }, - { - "type": "string", - "format": "uri", - "title": "Referent", - "$ref": "#/definitions/previewInResultsFalse" - } - ] - }, - "materialType": { - "type": "string", - "title": "Material type", - "$ref": "#/definitions/previewInResultsFalse" - }, - "name": { - "type": "string", - "maxLength": 128, - "title": "Name", - "cordra": { - "preview": { - "showInPreview": true, - "isPrimary": true - } - } - } - }, - "required": [ - "modified", - "midsLevel", - "physicalSpecimenId", - "institution" - ] - } - }, - "required": [ - "id", - "typeName", - "authoritative" - ] -} - diff --git a/oldcontent/json-examples-and-schemas/digital-specimen-object/example2-schema.json b/oldcontent/json-examples-and-schemas/digital-specimen-object/example2-schema.json deleted file mode 100644 index 3598bf7..0000000 --- a/oldcontent/json-examples-and-schemas/digital-specimen-object/example2-schema.json +++ /dev/null @@ -1,210 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "$ref": "#/definitions/Welcome", - "definitions": { - "Welcome": { - "type": "object", - "additionalProperties": false, - "properties": { - "id": { - "type": "string" - }, - "typeName": { - "type": "string" - }, - "authoritative": { - "$ref": "#/definitions/Authoritative" - }, - "images": { - "$ref": "#/definitions/Images" - }, - "payloads": { - "type": "array", - "items": { - "$ref": "#/definitions/Payload" - } - } - }, - "required": [ - "authoritative", - "id", - "images", - "payloads", - "typeName" - ], - "title": "Welcome" - }, - "Authoritative": { - "type": "object", - "additionalProperties": false, - "properties": { - "modified": { - "type": "string", - "format": "date-time" - }, - "midsLevel": { - "type": "integer" - }, - "physicalSpecimenId": { - "type": "string" - }, - "institution": { - "type": "array", - "items": { - "type": "string", - "qt-uri-protocols": [ - "https" - ] - } - }, - "materialType": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "institution", - "materialType", - "midsLevel", - "modified", - "name", - "physicalSpecimenId" - ], - "title": "Authoritative" - }, - "Images": { - "type": "object", - "additionalProperties": false, - "properties": { - "availableImages": { - "type": "array", - "items": { - "$ref": "#/definitions/AvailableImage" - } - } - }, - "required": [ - "availableImages" - ], - "title": "Images" - }, - "AvailableImage": { - "type": "object", - "additionalProperties": false, - "properties": { - "imageName": { - "type": "string" - }, - "source": { - "$ref": "#/definitions/SourceUnion" - }, - "mediaType": { - "type": "string" - }, - "imageWidth": { - "type": "string", - "format": "integer" - }, - "imageHeight": { - "type": "string", - "format": "integer" - }, - "xResolution": { - "type": "string" - }, - "yResolution": { - "type": "string" - }, - "colorSpace": { - "type": "string" - }, - "iccProfileName": { - "type": "string" - }, - "creator": { - "type": "string" - }, - "created": { - "type": "string" - }, - "project": { - "type": "string" - }, - "license": { - "type": "string" - } - }, - "required": [ - "colorSpace", - "created", - "creator", - "iccProfileName", - "imageHeight", - "imageName", - "imageWidth", - "license", - "mediaType", - "project", - "source", - "xResolution", - "yResolution" - ], - "title": "AvailableImage" - }, - "SourceClass": { - "type": "object", - "additionalProperties": false, - "properties": { - "$ref": { - "type": "string" - } - }, - "required": [ - "$ref" - ], - "title": "SourceClass" - }, - "Payload": { - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string" - }, - "filename": { - "type": "string" - }, - "mediaType": { - "type": "string" - }, - "size": { - "type": "integer" - } - }, - "required": [ - "filename", - "mediaType", - "name", - "size" - ], - "title": "Payload" - }, - "SourceUnion": { - "anyOf": [ - { - "$ref": "#/definitions/SourceClass" - }, - { - "type": "string", - "format": "uri", - "qt-uri-protocols": [ - "http" - ] - } - ], - "title": "SourceUnion" - } - } -} diff --git a/oldcontent/json-examples-and-schemas/digital-specimen-object/example3-opends-schema.json b/oldcontent/json-examples-and-schemas/digital-specimen-object/example3-opends-schema.json deleted file mode 100644 index 544b7b4..0000000 --- a/oldcontent/json-examples-and-schemas/digital-specimen-object/example3-opends-schema.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - -} \ No newline at end of file diff --git a/oldcontent/ods-ontology/ods-ont-intro.md b/oldcontent/ods-ontology/ods-ont-intro.md deleted file mode 100644 index 60d1f73..0000000 --- a/oldcontent/ods-ontology/ods-ont-intro.md +++ /dev/null @@ -1,37 +0,0 @@ -# The Ontology for open Digital Specimens (ODS) - -The Ontology for open Digital Specimens (ODS) situates open Digital Specimens in the relevant [OBO Foundry](http://www.obofoundry.org/) ontologies and extends from those roots to define the new concepts needed to support mass digitization and Digital Specimens on the Internet. - -## OBO Foundry Ontologies - -The relevant [OBO Foundry](http://www.obofoundry.org/) Ontologies are the following: - -- Ontology for Biomedical Investigations ([OBI](http://www.obofoundry.org/ontology/obi.html)): OBI is an ontology for the description of life-science and clinical investigations; -- Biological Collections Ontology ([BCO](http://www.obofoundry.org/ontology/bco.html)): BCO is an ontology to support the interoperability of biodiversity data, including data on museum collections, environmental/metagenomic samples, and ecological surveys; and, -- Information Artifact Ontology ([IAO](http://www.obofoundry.org/ontology/iao.html)): IAO is an ontology of information entities. - -For an explanation of how the BCO is related to the OBI and IAO ontologies, this recent (2018) book chapter on "*[Integrating and Managing Biodiversity Data with the Biocollections Ontology](http://ebooks.iospress.nl/volumearticle/49542)*" by Ramona Walls et al. is helpful. - -## Situating ODS in existing ontologies and extending therefrom - -With reference to the following figure, - -![new classes in ODS ontology (dark green)](/images/ods-newconcepts680.png) - -In the [OBI](http://www.obofoundry.org/ontology/obi.html) there is the concept of a ‘planned_process’ ([OBI_0000011](http://purl.obolibrary.org/obo/OBI_0000011)) that captures the idea of performing some kind of process that has previously been planned. Present examples (subclasses) include: carrying out investigations, assays, creating datasets, developing software and (of immediate relevance) collecting specimens ('specimen_collection_process',[OBI_000659](http://purl.obolibrary.org/obo/OBI_0000659)). - -The result of a specimen_collection_process is a specimen ([OBI_0100051](http://purl.obolibrary.org/obo/OBI_0100051)), which can be further elaborated as a PreservedSpecimen or a LivingSpecimen. And here we arrive at the conjunction between the ontologies of the OBO Foundry and the terms vocabularies/schema of TDWG [Darwin Core (DwC)](https://dwc.tdwg.org/) and [Access to Biological Collections Data (ABCD)](https://abcd.tdwg.org/) and its [Extension for Geosciences (EFG)](http://terms.tdwg.org/wiki/ABCD_EFG). - - -The concepts 'specimen_collection_process' and 'specimen' are replicated forward into the [BCO](http://www.obofoundry.org/ontology/bco.html) as [BCO:OBI_0000659](http://www.ontobee.org/ontology/BCO?iri=http://purl.obolibrary.org/obo/OBI_0000659) and [BCO:OBI_0100051](http://www.ontobee.org/ontology/BCO?iri=http://purl.obolibrary.org/obo/OBI_0100051) respectively. - -ODS situates the act of planned digitization activities as a new kind of OBI:planned_process that we name as 'digitization_event' or 'digitization_process' (ODS_00000nn). This sits alongside the familiar notion of collecting specimens as another major activity performed by institutions holding natural science collections. - -The output of a digitization_process is a new class ‘digital specimen’ (ODS_00000nn). This must be considered as a new subclass of ‘information_content_entity’ ([IAO:0000030](http://purl.obolibrary.org/obo/IAO_0000030)) in the IAO), being ‘a result of a digitisation event or process’. We consdier a new subclass because the existing subclasses don't seem appropriate. Subclass 'data_item' ([IAO:0000027](http://purl.obolibrary.org/obo/IAO_0000027)) seems rather too general. - -*To do: digitization_event or digitization_process? Go back to earlier notes and have a look at why is event rather than process.* - -*To do: assign numbers/IRI to the new concepts in ODS - two above.* - - -END. \ No newline at end of file diff --git a/oldcontent/ods-ontology/terms/index.html b/oldcontent/ods-ontology/terms/index.html deleted file mode 100644 index 6a733ec..0000000 --- a/oldcontent/ods-ontology/terms/index.html +++ /dev/null @@ -1,6 +0,0 @@ - - - - - Placeholder for list and IRIs of openDS terms - \ No newline at end of file diff --git a/oldcontent/serialization.md b/oldcontent/serialization.md deleted file mode 100644 index 3aa0802..0000000 --- a/oldcontent/serialization.md +++ /dev/null @@ -1,7 +0,0 @@ -# Serialization of openDS - -The serialization of openDS must comply with the requirements of Section 4 and Appendix A of the [Digital Object Interface Protocol (DOIP)](https://hdl.handle.net/0.DOIP/DOIPV2.0) specification. - -*Further requirements to be written.* - -END. \ No newline at end of file diff --git a/oldcontent/templates/template-issue-classdefinition.md b/oldcontent/templates/template-issue-classdefinition.md deleted file mode 100644 index abfe345..0000000 --- a/oldcontent/templates/template-issue-classdefinition.md +++ /dev/null @@ -1,26 +0,0 @@ -# Template markdown for Github issue - -**Template for an issue on Class Definition** - -Title of the issue must be "Class:NewClassName" - -Use the md table below as the body of the issue - - - -| | | -| ---- | ---- | -| **Class level** | *one of Abstract, Concrete or Extender* | -| **Parent** | *name of parent class* | -| **Definition** | *definition of the class* | -| **Repeatable** | *yes or no* | -| **Relationships** | *NewClassName* (*e.g.,* 1 to many) <-> *Another ClassName* (* e.g.,* 0 to many) | -| **Potential standards/vocabularies/ontologies to adopt** | *List these* *e.g., DataCite metadata schema (https://schema.datacite.org/meta/kernel-4.3/)* | -| **Notes** | | - - -Attach labels to the issue (with correct colours, corresponding to Class Index spreadsheet): - -- Class:NewClassName -- data model - diff --git a/oldcontent/templates/template-issue-propertydefinition.md b/oldcontent/templates/template-issue-propertydefinition.md deleted file mode 100644 index a359910..0000000 --- a/oldcontent/templates/template-issue-propertydefinition.md +++ /dev/null @@ -1,28 +0,0 @@ -# Template markdown for Github issue - -**Template for an issue on Property Definition** - -Title of the issue must be "Property:newPropertyName" - -Use the md table below as the body of the issue - - -| | | -| ---- | ---- | -| **Definition** | *definition of the property* | -| **Existing property** | *e.g., DwC term* | -| **Existing class** | | -| **Existing property identifier** | *e.g., IRI* | -| **Format** | *e.g.,* Text | -| **Required** | *yes or no* | -| **Repeatable** | *yes or no* | -| **Constraints** | | -| **Examples** | *example1* \| *example2* | -| **Notes** | | - - -Attach labels to the issue (with correct colours, corresponding to Class Index spreadsheet): - -- Class:ClassName *(to which the property belongs)* -- data model - diff --git a/oldcontent/templates/template-model-classdefinition.md b/oldcontent/templates/template-model-classdefinition.md deleted file mode 100644 index 55a7bb9..0000000 --- a/oldcontent/templates/template-model-classdefinition.md +++ /dev/null @@ -1,47 +0,0 @@ -# Template markdown for a Class Definition - -1. Use the following markdown template for each new class definition. -2. Copy and paste the property template part as many times as needed. -3. Fill the Header section with the details from the resolved class definition issue. -4. Fill a property section with the details from the resolved property definition issue. - - - -# ClassName - -| | | -| ---- | ---- | -| **Type** | | -| **Hierarchy** | | -| **Range** | | -| **Potential standards/vocabularies/ontologies to adopt** | | -| **Notes** | | - - -## Header (class) - -| | | -| ---- | ---- | -| **Parent** | | -| **Definition** | | -| **Repeatable** | | -| **Relationships** | | -| **Potential standards/vocabularies/ontologies to adopt** | | -| **Notes** | | - -### property1Name (property) - -| | | -| ---- | ---- | -| **Definition** | | -| **Dimension** | | -| **Existing property** | | -| **Existing class** | | -| **Existing property identifier** | | -| **Format** | | -| **Required** | | -| **Repeatable** | | -| **Constraints** | | -| **Examples** | | -| **Notes** | | -