Moved dei-extension-schema.json from _static to extras

ThreeSixtyGiving · Oct 23, 2023 · 646f3ba · 646f3ba
1 parent 1ccd942
commit 646f3ba
Show file tree

Hide file tree

Showing 8 changed files with 221 additions and 61 deletions.
diff --git a/documentation/dei/index.md b/documentation/dei/index.md
diff --git a/documentation/extensions/dei/governance.md b/documentation/extensions/dei/governance.md
@@ -0,0 +1,37 @@
+# Governance and Versioning
+
+As an extension to the 360Giving Data Standard, the DEI Extension is managed outside of the [governance process](https://standard.threesixtygiving.org/en/latest/about/governance/) of the 360Giving Data Standard itself.
+
+360Giving is the steward of the DEI Extension. Our CEO is responsible for its day-to-day management, supported by a Product Manager and an external specialist technical team, Open Data Services Coop.
+
+## Aims and Approach
+
+Our aims and approach for maintaining the DEI Extension are as follows:
+
+1. Compatibility with the 360Giving Data Standard
+To maintain compatibility with the latest release of the 360Giving Data Standard. 
+
+2. Compatibility with the DEI Data Standard
+To maintain compatibility with the DEI Data Standard itself whenever possible. Updates to the DEI Extension will be issued in a timely manner to bring it in line with changes to the taxonomy structure and codes included in the DEI Data Standard, as well as any guidance about how to apply this to publishing the data alongside 360Giving data.
+
+3. Use semantic versioning
+To use semantic versioning to version this extension: MAJOR updates will not be compatible with previous versions of the extension, MINOR updates will add new features that are backwards compatible, and PATCH updates will fix bugs and amend documentation. 
+
+4. Consider stakeholders needs in the revision process
+To consider stakeholders needs and follow [360Giving Data Standard revision processes](https://standard.threesixtygiving.org/en/latest/about/governance/#the-revision-process) when making updates to the DEI Extension.
+
+## Versions
+
+The DEI Extension is versioned using [Semantic Versioning](https://semver.org/).
+
+The version number of the DEI Extension and update processes and schedules are *separate* from each: the [360Giving Data Standard](https://standard.threesixtygiving.org/en/latest/about/governance/#versions); and the [DEI Data Standard](https://www.funderscollaborativehub.org.uk/collaborations/dei-data-standard).
+
+This means there may be times when data shared using the DEI Extension does not match the latest version of the DEI Data Standard.
+
+The version number and all notable changes are documented by Release via the Changelog.
+
+## Changelog
+
+All notable changes to the DEI Extension are documented by Release via the extension's [Github repository](https://github.com/ThreeSixtyGiving/360-dei/releases)
+
+
diff --git a/documentation/dei/guidance.md → documentation/extensions/dei/guidance.md b/documentation/dei/guidance.md → documentation/extensions/dei/guidance.md
@@ -1,4 +1,4 @@
-# DEI Guidance
+# Guidance for Publishers
 
 ## Introduction
 

diff --git a/documentation/extensions/dei/index.md b/documentation/extensions/dei/index.md
@@ -0,0 +1,17 @@
+# Diversity, Equity, and Inclusion Extension
+
+This is the documentation for the DEI Extension provided by 360Giving. The DEI Extension is an extension to the 360Giving Data Standard which allows [Diversity, Equality, and Inclusion (DEI) Data Standard](https://www.funderscollaborativehub.org.uk/dei-data-standard) data to be published alongside [360Giving data](https://standard.threesixtygiving.org/en/latest/#), so that it can be validated and used in 360Giving tools.
+
+The DEI Data Standard is developed and maintained by the DEI Data Group, with technical support provided by 360Giving.
+
+The DEI Extension has been developed and is maintained by 360Giving to support new and existing 360Giving publishers to include DEI Data Standard data in their 360Giving data files.
+
+```eval_rst
+.. toctree::
+   :maxdepth: 3
+
+   governance
+   reference
+   guidance
+```
+
diff --git a/documentation/dei/reference.md → documentation/extensions/dei/reference.md b/documentation/dei/reference.md → documentation/extensions/dei/reference.md
@@ -1,50 +1,4 @@
-# DEI Reference
-
-## About
-
-This is the documentation for the DEI Extension provided by 360Giving. The DEI Extension is an extension to the 360Giving Data Standard which allows [Diversity, Equality, and Inclusion (DEI) Data Standard](https://www.funderscollaborativehub.org.uk/dei-data-standard) data to be published alongside [360Giving data](https://standard.threesixtygiving.org/en/latest/#), so that it can be validated and used in 360Giving tools.
-
-The DEI Data Standard is developed and maintained by the DEI Data Group, with technical support provided by 360Giving.
-
-The DEI Extension has been developed and is maintained by 360Giving to support new and existing 360Giving publishers to include DEI Data Standard data in their 360Giving data files.
-
-### Governance and Versioning
-
-As an extension to the 360Giving Data Standard, the DEI Extension is managed outside of the [governance process](https://standard.threesixtygiving.org/en/latest/about/governance/) of the 360Giving Data Standard itself.
-
-360Giving is the steward of the DEI Extension. Our CEO is responsible for its day-to-day management, supported by a Product Manager and an external specialist technical team, Open Data Services Coop.
-
-#### Aims and Approach
-
-Our aims and approach for maintaining the DEI Extension are as follows:
-
-1. Compatibility with the 360Giving Data Standard
-To maintain compatibility with the latest release of the 360Giving Data Standard. 
-
-2. Compatibility with the DEI Data Standard
-To maintain compatibility with the DEI Data Standard itself whenever possible. Updates to the DEI Extension will be issued in a timely manner to bring it in line with changes to the taxonomy structure and codes included in the DEI Data Standard, as well as any guidance about how to apply this to publishing the data alongside 360Giving data.
-
-3. Use semantic versioning
-To use semantic versioning to version this extension: MAJOR updates will not be compatible with previous versions of the extension, MINOR updates will add new features that are backwards compatible, and PATCH updates will fix bugs and amend documentation. 
-
-4. Consider stakeholders needs in the revision process
-To consider stakeholders needs and follow [360Giving Data Standard revision processes](https://standard.threesixtygiving.org/en/latest/about/governance/#the-revision-process) when making updates to the DEI Extension.
-
-#### Versions
-
-The DEI Extension is versioned using [Semantic Versioning](https://semver.org/).
-
-The version number of the DEI Extension and update processes and schedules are *separate* from each: the [360Giving Data Standard](https://standard.threesixtygiving.org/en/latest/about/governance/#versions); and the [DEI Data Standard](https://www.funderscollaborativehub.org.uk/collaborations/dei-data-standard).
-
-This means there may be times when data shared using the DEI Extension does not match the latest version of the DEI Data Standard.
-
-The version number and all notable changes are documented by Release via the Changelog.
-
-#### Changelog
-
-All notable changes to the DEI Extension are documented by Release via the extension's [Github repository](https://github.com/ThreeSixtyGiving/360-dei/releases)
-
-## Technical Reference
+# Technical Reference
 
 ### Extension Structure Overview
 
@@ -83,17 +37,10 @@ For a publisher of data using this extension this means that:
 
 This section contains a reference for the Extension’s schema
 
-#### Grant and DEI Details
-
-The extension defines the `deiDetails` field, which is a new object in the 360Giving Grant Schema
-
-TODO schema table for grants.deiDetails
 
-#### DEI Application Area
-
-The extension defines a new `DeiApplicationArea` with the following fields:
-
-TODO schema table for DeiApplicationArea
+```eval_rst
+.. jsonschema-titles:: ../../extras/dei-extension-schema.json
+```
 
 ### Codelists
 
@@ -103,18 +50,47 @@ The extension adds several codelists to promote interoperability between dataset
 
 A codelist to declare whether DEI Data Standard questions were asked for this grant, and how.
 
+
+```eval_rst
+.. csv-table:: 
+   :url: https://raw.githubusercontent.com/ThreeSixtyGiving/360-dei/refactor-to-minimal/codelists/askedStatus.csv
+   :header-rows: 1
+   :widths: auto
+```
+
 #### Available Options
 
 A codelist to declare which answer options were available to the respondents.
 
+```eval_rst
+.. csv-table:: 
+   :url: https://raw.githubusercontent.com/ThreeSixtyGiving/360-dei/refactor-to-minimal/codelists/availableOptions.csv
+   :header-rows: 1
+   :widths: auto
+```
+
 #### Reply Status
 
 A codelist to declare whether a reply to DEI Data Standard questions was received or not.
 
+```eval_rst
+.. csv-table:: 
+   :url: https://raw.githubusercontent.com/ThreeSixtyGiving/360-dei/refactor-to-minimal/codelists/replyStatus.csv
+   :header-rows: 1
+   :widths: auto
+```
+
 #### Taxonomy Codes
 
 The authoritative source for the DEI Taxonomy codes vocabulary is the [DEI Data Standard](https://www.funderscollaborativehub.org.uk/collaborations/dei-data-standard) and should take precedence over all other sources of information about the DEI Taxonomy codes, including this codelist.
 
 The DEI Extension for 360Giving creates and maintains this codelist by taking the hierarchical codes defined in the DEI Data Standard, encoding them into JSON, and then generating this codelist automatically. This is necessary to provide a machine-readable codelist to support validation.
 
 Please see the [Guiding Principles](#guiding-principles) section for more information on how we respond to updates in the DEI Standard.
+
+```eval_rst
+.. csv-table:: 
+   :url: https://raw.githubusercontent.com/ThreeSixtyGiving/360-dei/refactor-to-minimal/codelists/taxonomyCodes.csv
+   :header-rows: 1
+   :widths: auto
+```
diff --git a/documentation/extensions/index.md b/documentation/extensions/index.md
@@ -0,0 +1,23 @@
+# Extensions Documentation
+
+This is a holding page for the Extension Section. This will be updated with proper copy before deployment.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Dui nunc mattis enim ut tellus. Auctor neque vitae tempus quam pellentesque nec nam aliquam sem. Sit amet porttitor eget dolor morbi non. Dolor purus non enim praesent elementum facilisis. Sapien pellentesque habitant morbi tristique. Lorem ipsum dolor sit amet consectetur adipiscing. Nulla malesuada pellentesque elit eget gravida cum sociis. Fames ac turpis egestas integer eget. Est pellentesque elit ullamcorper dignissim. Ornare arcu dui vivamus arcu felis bibendum ut. Vitae tempus quam pellentesque nec nam aliquam sem et tortor. Ut tortor pretium viverra suspendisse. Tellus at urna condimentum mattis pellentesque id. In ornare quam viverra orci sagittis eu volutpat odio. Velit laoreet id donec ultrices tincidunt. Porttitor rhoncus dolor purus non enim praesent elementum facilisis. Amet justo donec enim diam vulputate. Nisl nisi scelerisque eu ultrices vitae. In metus vulputate eu scelerisque felis.
+
+Commodo elit at imperdiet dui accumsan sit amet nulla. Mollis aliquam ut porttitor leo a diam sollicitudin tempor. Natoque penatibus et magnis dis parturient montes nascetur ridiculus mus. Ut tortor pretium viverra suspendisse potenti nullam ac tortor vitae. Nascetur ridiculus mus mauris vitae ultricies. Nibh praesent tristique magna sit amet. Sem nulla pharetra diam sit amet nisl suscipit adipiscing. Mattis enim ut tellus elementum sagittis vitae et. Facilisi morbi tempus iaculis urna id volutpat. Suspendisse faucibus interdum posuere lorem ipsum dolor. Vitae congue mauris rhoncus aenean. Lacus viverra vitae congue eu consequat ac felis donec et. Imperdiet massa tincidunt nunc pulvinar sapien. Interdum velit euismod in pellentesque massa placerat duis ultricies lacus. Tristique magna sit amet purus gravida quis blandit turpis cursus. Sodales ut eu sem integer vitae justo eget. Ut enim blandit volutpat maecenas. Eget magna fermentum iaculis eu non diam phasellus vestibulum.
+
+Amet venenatis urna cursus eget nunc scelerisque. Eget velit aliquet sagittis id consectetur purus. Sit amet porttitor eget dolor morbi non. A diam sollicitudin tempor id eu nisl. Ut morbi tincidunt augue interdum velit. Mauris nunc congue nisi vitae suscipit tellus. In eu mi bibendum neque egestas. Dictum sit amet justo donec enim diam vulputate ut pharetra. Nam aliquam sem et tortor consequat id porta nibh. Enim facilisis gravida neque convallis a cras semper auctor. Ac feugiat sed lectus vestibulum mattis ullamcorper velit. Rutrum quisque non tellus orci ac auctor augue mauris augue. Sed egestas egestas fringilla phasellus. Tortor id aliquet lectus proin nibh. Sed id semper risus in hendrerit. Neque laoreet suspendisse interdum consectetur libero id. At lectus urna duis convallis convallis tellus id interdum.
+
+Sapien eget mi proin sed libero enim. Nullam vehicula ipsum a arcu cursus vitae. Nisl tincidunt eget nullam non nisi. Eu augue ut lectus arcu bibendum at varius. Imperdiet massa tincidunt nunc pulvinar. Ultricies lacus sed turpis tincidunt id aliquet risus feugiat. Et ultrices neque ornare aenean euismod. Fermentum posuere urna nec tincidunt praesent semper feugiat nibh sed. Mattis enim ut tellus elementum sagittis. Nunc sed velit dignissim sodales ut eu. Duis at consectetur lorem donec massa sapien faucibus et molestie. Bibendum ut tristique et egestas quis ipsum suspendisse ultrices.
+
+Nulla facilisi nullam vehicula ipsum a arcu cursus vitae. Velit euismod in pellentesque massa placerat duis ultricies lacus. Tellus cras adipiscing enim eu turpis egestas pretium aenean pharetra. Odio ut enim blandit volutpat maecenas volutpat blandit. Euismod nisi porta lorem mollis aliquam ut porttitor leo. Iaculis at erat pellentesque adipiscing commodo elit at imperdiet. Dignissim convallis aenean et tortor at risus viverra adipiscing. Netus et malesuada fames ac turpis egestas maecenas pharetra. Vehicula ipsum a arcu cursus. Quis eleifend quam adipiscing vitae proin sagittis nisl rhoncus mattis. Vitae tempus quam pellentesque nec nam. Diam vel quam elementum pulvinar etiam non quam lacus. Magna etiam tempor orci eu. Vel eros donec ac odio tempor orci dapibus. Accumsan tortor posuere ac ut consequat semper viverra nam. Erat velit scelerisque in dictum non consectetur a erat nam. Quam lacus suspendisse faucibus interdum posuere. Duis at consectetur lorem donec massa sapien. Diam sollicitudin tempor id eu nisl nunc mi. Et malesuada fames ac turpis egestas maecenas pharetra convallis.
+
+
+```eval_rst
+
+.. toctree::
+   :maxdepth: 3
+
+   dei/index
+
+```
diff --git a/documentation/extras/dei-extension-schema.json b/documentation/extras/dei-extension-schema.json
@@ -0,0 +1,109 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "definitions": {
+    "DeiApplicationArea": {
+      "type": "object",
+      "description": "A DEI application area used to collect information about whether a particular question was asked, responded to, and additional information. It also contains the response information under the Response fields.",
+      "required": [
+        "askedStatus"
+      ],
+      "properties": {
+        "askedStatus": {
+          "type": "string",
+          "title": "Asked Status",
+          "description": "A code referring to how this question was asked. The value for this field should be drawn from the Asked Status codelist.",
+          "codelist": "askedStatus.csv",
+          "openCodelist": false
+        },
+        "replyStatus": {
+          "type": "string",
+          "title": "Reply Status",
+          "description": "A code referring to the status of the reply to this question. The value for this field should be drawn from the Reply Status codelist.",
+          "codelist": "replyStatus.csv",
+          "openCodelist": false
+        },
+        "availableOptions": {
+          "type": "array",
+          "title": "Available Options",
+          "description": "Code(s) referring to options which were available when the question was asked. The value for these codes should be drawn from the Available Options codelist.",
+          "items": {
+            "type": "string",
+            "codelist": "availableOptions.csv",
+            "openCodelist": false
+          },
+          "uniqueItems": true
+        },
+        "additionalDetails": {
+          "type": "string",
+          "title": "Additional Details",
+          "description": "A free text field to include any additional details or rationales that may be important to this context."
+        },
+        "response": {
+          "type": "object",
+          "title": "DEI Response",
+          "description": "A response to a DEI Application area, containing information such as the taxonomy codes selected and any lived experience or geography responses.",
+          "properties": {
+            "taxonomyCodes": {
+              "title": "Taxonomy Codes",
+              "description": "The Taxonomy Codes selected from the DEI Taxonomies. The value for these codes should be drawn from the Taxonomy Codes codelist.",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "codelist": "taxonomyCodes.csv",
+                "openCodelist": false
+              },
+              "uniqueItems": true
+            },
+            "livedExperience": {
+              "type": "string",
+              "title": "Lived Experience",
+              "description": "A free text description of other types of lived experience that is not drawn from the Taxonomy."
+            },
+            "geography": {
+              "type": "string",
+              "title": "Geography",
+              "description": "A free text description that is not drawn from a vocabulary but instead relates to a particular geographical area."
+            }
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "deiDetails": {
+      "type": "object",
+      "title": "DEI Details",
+      "description": "The DEI Details for this grant. Contains information about separate application areas and the responses to them.",
+      "required": [
+        "leadership",
+        "mission",
+        "project"
+      ],
+      "properties": {
+        "deiVersion": {
+          "type": "string",
+          "title": "DEI Data Standard Version",
+          "description": "The version of the DEI Data Standard that this data uses e.g. 1.1",
+          "pattern": "^[1-9]+\\.[1-9]\\d*$"
+        },
+        "purposes": {
+          "type": "string",
+          "title": "Purposes",
+          "description": "The purposes of collecting this data."
+        },
+        "leadership": {
+	  "title": "Leadership",
+          "$ref": "#/definitions/DeiApplicationArea"
+        },
+        "mission": {
+	  "title": "Mission",
+          "$ref": "#/definitions/DeiApplicationArea"
+        },
+        "project": {
+	  "title": "Project",
+          "$ref": "#/definitions/DeiApplicationArea"
+        }
+      }
+    }
+  }
+}
diff --git a/documentation/index.md b/documentation/index.md
@@ -37,6 +37,7 @@ This section features information about governance and change management of the
    guidance/index
    individuals/index
    technical/index
+   extensions/index
    about/index
 
 ```