From 551e309daf945b344d2ca4eaff9206ad0a012c40 Mon Sep 17 00:00:00 2001 From: raphaelgazzotti Date: Tue, 3 Dec 2024 09:09:15 +0100 Subject: [PATCH] Correct typos and add namespace changes. --- .../contribution_guidelines/vocabulary.rst | 16 ++++++++++++++++ .../getting_started/openMINDS_collections.rst | 2 +- .../getting_started/openMINDS_instances.rst | 6 +++--- .../getting_started/research_activities.rst | 4 ++-- docs/shared/glossary.rst | 8 ++++---- 5 files changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/shared/contribution_guidelines/vocabulary.rst b/docs/shared/contribution_guidelines/vocabulary.rst index fcae0460..b7ed2382 100644 --- a/docs/shared/contribution_guidelines/vocabulary.rst +++ b/docs/shared/contribution_guidelines/vocabulary.rst @@ -20,6 +20,14 @@ In this JSON file, each vocabulary implementation for a single schema type is st "SCHEMATYPE": { "color": "HEXCOLOR", "description": "SCHEMATYPE_DESCRIPTION", + "hasNamespace": [ + { + "inVersions": [ + "VERSION" + ], + "namespace": "SCHEMATYPE_NAMESPACE" + } + ], "isPartOfVersion": [ "VERSION" ], @@ -54,6 +62,14 @@ In this JSON file, each vocabulary implementation for a single property is struc "multiline": "BOOLEAN" }, "description": "PROPERTYNAME_DESCRIPTION", + "hasNamespace": [ + { + "inVersions": [ + "VERSION" + ], + "namespace": "PROPERTYNAME_NAMESPACE" + } + ], "label": "PROPERTYLABEL", "labelPlural": "PROPERTYLABEL", "name": "PROPERTYNAME_SHORT", diff --git a/docs/shared/getting_started/openMINDS_collections.rst b/docs/shared/getting_started/openMINDS_collections.rst index f4fabd51..e500cc5e 100644 --- a/docs/shared/getting_started/openMINDS_collections.rst +++ b/docs/shared/getting_started/openMINDS_collections.rst @@ -156,7 +156,7 @@ These separate files should be stored in a dedicated collection directory. The o |-- tricia-marie-mcmillan.jsonld `-- zaphod-beeblebrox.jsonld -If the collection contains instances that contain sensitive information, these instances can be stored in a protected subdirectory. For our example directories above that could look like this: +If the collection contains instances with sensitive information, these instances can be stored in a protected subdirectory. For our example directories above that could look like this: .. tabs:: collection-directory diff --git a/docs/shared/getting_started/openMINDS_instances.rst b/docs/shared/getting_started/openMINDS_instances.rst index b777088c..9bc22113 100644 --- a/docs/shared/getting_started/openMINDS_instances.rst +++ b/docs/shared/getting_started/openMINDS_instances.rst @@ -2,7 +2,7 @@ openMINDS instances ################### -openMINDS metadata instances should be provided as JSON-LD documents (file extension: ``*.jsonld``) and comply to the openMINDS schema type they reference. In the following we will explain how openMINDS instances look like for simple examples. +openMINDS metadata instances should be provided as JSON-LD documents (file extension: ``*.jsonld``) and comply to the openMINDS schema type they reference. In the following sections, we will explain how openMINDS instances look like for simple examples. Creating a minimal instance ########################### @@ -62,14 +62,14 @@ Both compact syntaxes can be interpreted by any tool that is aware of the JSON-L **"@id"**: The JSON-LD keyword ``"@id"`` is used to provide a unique, referable identifier for an instance in a linked metadata collection (cf. `Linking instances`_). In accordance with the JSON-LD specifications, the ``"@id"`` has to be an IRI, a compact IRI or a blank node ID. Which option is chosen is user dependent. However, be aware that within a linked metadata collection each instance has to have a unique ``"@id"``. Our recommendations are as follows: - For a local metadata collection the ``"@id"`` of instances can be defined as blank node ID. A blank node ID has the form of ``"_:suffix"``. The suffix can either be a unique human-readable label or a numerical identifier. Be aware that blank node identifier are not persistent or portable. -- For a portable metadata collection the ``"@id"`` of instances have to be replaced with globally unique and persistent identifiers (e.g., a system-wide IRI prefix in combination with an universially unique identifier (UUID)). +- For a portable metadata collection the ``"@id"`` of instances have to be replaced with globally unique and persistent identifiers (e.g., a system-wide IRI prefix in combination with an universally unique identifier (UUID)). **"@type"**: The JSON-LD keyword ``"@type"`` is used to set the type of an instance or an embedded typed object within an instance. The ``"@type"`` clearly identifies the metadata schema that should be used to validate the content of an instance or an embedded typed object. Linking instances ################# -Connections between instances of a linked metadata collection are formed by refering to instance's unique identifiers. The "Person" schema tells us that the property `"contactInformation" `_ is actually expecting a link (edge) to another instance (object) of type "ContactInformation". Let us create an instance of type "ContactInformation" and link it from a "Person" instance. +Connections between instances of a linked metadata collection are formed by referring to instance's unique identifiers. The "Person" schema tells us that the property `"contactInformation" `_ is actually expecting a link (edge) to another instance (object) of type "ContactInformation". Let us create an instance of type "ContactInformation" and link it from a "Person" instance. If we check the constraints of the `"ContactInformation" schema `_, we learn that an instance of this type only requires the property `"email" `_ defined through a single value of data type "string". A respective "ContactInformation" instance could therefore look like this: diff --git a/docs/shared/getting_started/research_activities.rst b/docs/shared/getting_started/research_activities.rst index a96d9296..13e998b8 100644 --- a/docs/shared/getting_started/research_activities.rst +++ b/docs/shared/getting_started/research_activities.rst @@ -14,6 +14,6 @@ For the most basic level to indicate what was done, a `"DatasetVersion" `_ requires a user to name and describe the applied technical procedure in form of a generic recipe (should be reusable across dataset verions). In addition, the technical protocol should be tagged with the respectively used techniques. These techniques should be at least a subset of the techniques tagged onto the dataset version the technical protocol is linked to. +A technical `"Protocol `_ requires a user to name and describe the applied technical procedure in form of a generic recipe (should be reusable across dataset versions). In addition, the technical protocol should be tagged with the respectively used techniques. These techniques should be at least a subset of the techniques tagged onto the dataset version the technical protocol is linked to. -A `"BehavioralProtocol" `_ requires a user to name and describe the conducted behavioural task or paradigm in form of a generic recipe (should be reusable across dataset verions). When applicable, the behavioral protocol should be tagged with the respectively used stimulus types and stimulation techniques. These stimulation techniques should be at least a subset of the techniques tagged onto the dataset version the behavioural protocol is linked to. +A `"BehavioralProtocol" `_ requires a user to name and describe the conducted behavioural task or paradigm in form of a generic recipe (should be reusable across dataset versions). When applicable, the behavioral protocol should be tagged with the respectively used stimulus types and stimulation techniques. These stimulation techniques should be at least a subset of the techniques tagged onto the dataset version the behavioural protocol is linked to. diff --git a/docs/shared/glossary.rst b/docs/shared/glossary.rst index d0e0a0ed..0c179a94 100644 --- a/docs/shared/glossary.rst +++ b/docs/shared/glossary.rst @@ -11,19 +11,19 @@ Glossary Fundamental structured (meta)data representation that consists of two elements: a value that can specify a (meta)data variable (e.g., 'Homo sapiens') and a property defining the context of the value (e.g., 'species'). Note that a value can be simple (e.g., string, number, array) or complex (e.g., property-value pair). Synonyms: attribute-value pair, field-value pair, key-value pair, name-value pair. entity-property-value triple - Fundamental structured (meta)data representation that consists of three elements: a value that can specify a (meta)data variable (e.g., 'Jane'), a property defining the context of the value (e.g., 'given name'), and an entity defining the context of the property (e.g., 'Person'). Note that entity types are typically captitalized and properties remain in lower case. Moreover, note that the same entity can define the context of multiple properties (e.g., the properties 'given name' and 'family name' both belong to the entity 'Person'). Synonyms: entity-attribute-value triple, object-attribute-value triple, object-property-value triple, subject-attribute-value triple, subject-property-value triple. + Fundamental structured (meta)data representation that consists of three elements: a value that can specify a (meta)data variable (e.g., 'Jane'), a property defining the context of the value (e.g., 'given name'), and an entity defining the context of the property (e.g., 'Person'). Note that entity types are typically capitalized and properties remain in lower case. Moreover, note that the same entity can define the context of multiple properties (e.g., the properties 'given name' and 'family name' both belong to the entity 'Person'). Synonyms: entity-attribute-value triple, object-attribute-value triple, object-property-value triple, subject-attribute-value triple, subject-property-value triple. metadata instance - Instanciation of metadata in form of property-value pairs or entity-property-value triples. There are various file formats used to instanciated metadata of different data type (tables or associative arrays). A typical metadata table format is CSV and a typical metadata associative array format is JSON. + Instantiation of metadata in form of property-value pairs or entity-property-value triples. There are various file formats used to instantiated metadata of different data type (tables or associative arrays). A typical metadata table format is CSV and a typical metadata associative array format is JSON. metadata schema - Specification of a set of required or optional properties and the type and number of expected values for each property for a certain entity type (schema type). For exmaple, the schema type 'Person', defines that the property 'given name' is required with one expected value of type 'string', and the property 'family name' is optional with also one expected value of type 'string'. A metadata schema is used as constrictive template to create consistently structured metadata instances for the same type of entity. + Specification of a set of required or optional properties and the type and number of expected values for each property for a certain entity type (schema type). For example, the schema type 'Person', defines that the property 'given name' is required with one expected value of type 'string', and the property 'family name' is optional with also one expected value of type 'string'. A metadata schema is used as constrictive template to create consistently structured metadata instances for the same type of entity. metadata model Specification of multiple metadata schemas and the semantic relations that can be formed between instances constraint by these schemas. For example, the schema 'Dataset' defines that an instance of type 'Dataset' can be linked to multiple instances of type 'Person' through the relation definition 'has authors'. linked metadata instances - Instanciation of metadata in form of entity-property-value triples that are equiped with unique identifiers in order to allow for non-ambiguous connections between the instances through those identifiers. A typical format for storing linked metadata instances is JSON-LD. The type and unique identifier of a JSON-LD instance are always defined under the properties `'@type'` and `'@id'`. + Instantiation of metadata in form of entity-property-value triples that are equipped with unique identifiers in order to allow for non-ambiguous connections between the instances through those identifiers. A typical format for storing linked metadata instances is JSON-LD. The type and unique identifier of a JSON-LD instance are always defined under the properties `'@type'` and `'@id'`. graph database Database that uses semantically queryable graph structures, where nodes (metadata instances) represent conceptual entities with property-value pairs and edges represent the relationships between the nodes. Graph databases can be designed schemaless, and are therefore often used for highly heterogeneous data collections. However, most graph database management systems use metadata models to constrain and validate the nodes and edges to increase the robustness of data queries.