Schema test and raw-loader install

[ross-spencer]

To run: npm i && npm start

Example embedding JSON into a page and making it downloadable. Result is as follows.

Connected to: #24

[Christian-MK]

Could be used to make schema json's renderable and downloadable through docs

envisioning something like

├─Introduction
├─Orcfax solution
├─Fact token
├─FAQ
├─static
│   ├─ CER
|   |   ├─ CEX
│   |   |   ├─ fact-statment.json // schema.org definitions for each type and property
│   |   |   ├─ fact-statment-datum.json
│   |   |   ├─ message.json
│   |   |   └─ validation.json
│   |   └─ DEX
│   |   |   ├─ fact-statment.json // schema.org definitions for each type and property
│   |   |   ├─ fact-statment-datum.json
│   |   |   ├─ message.json
│   |   |   └─ validation.json
|   ├─  Other // allows us to continue adding other feed types
|   └─img

[ross-spencer]

Just updated to rc8 here: https://github.com/orcfax/fact-statements/tree/main/v3.rc/rc8 with the modification to fix the dex text to make it sound less like an API.

What do you think the next steps are for this PR @Christian-MK?

[Christian-MK]

What do you think the next steps are for this PR @Christian-MK?

Well I should make sure I clearly understand what we want out of this. Going back to the vision I shared above, are we looking to add json files for each object in an archival packages with definitions for each of the schema.org types/properties? And once these are added, import them into a feed overview page where they can be downloaded?

[ross-spencer]

are we looking to add json files for each object in an archival packages with definitions for each of the schema.org types/properties? And once these are added, import them into a feed overview page where they can be downloaded?

Mostly! To begin, I think we could satisfy this with a cer-schema description with:

• Page per exemplar object type, e.g. 1xvalidation, 1xmessage (DEX), 1xmessage(CEX), 1xdatum, and so on.
• Describe each of the schema.org types/properties.
• Provide one example of the resulting JSON.

Not sure they need to then also be in a feed overview/be downloadable, but I think they should be copy and pastable using the mechanism above.

One of the goals is to support future development of the schema from a specification-first perspective -- rn we use code first to have a lot of these conversations. Once we have a specification first approach that should make it easier for ourselves and others to create conforming outputs.

[Christian-MK]

Mostly! To begin, I think we could satisfy this with a cer-schema description with:

• Page per exemplar object type, e.g. 1xvalidation, 1xmessage (DEX), 1xmessage(CEX), 1xdatum, and so on.
• Describe each of the schema.org types/properties.
• Provide one example of the resulting JSON.

@ross-spencer Let me know what you think about the last two commits. I've added a page for each object and have added type/property descriptions to /CER/CEX/fact-statement.md as an example for what could be done for each.

I've also added the resulting jsons (per rc8) so that it can be referenced from either the local or static directories depending on which way you want to go.

[ross-spencer]

@Christian-MK looks great, and then maybe something like this?

Just adding the lines in this diff:

diff --git a/docs/Feeds/CER/CEX/fact-statement.md b/docs/Feeds/CER/CEX/fact-statement.md
index b5cf1be..67f26ce 100644
--- a/docs/Feeds/CER/CEX/fact-statement.md
+++ b/docs/Feeds/CER/CEX/fact-statement.md
@@ -4,6 +4,9 @@ sidebar_position: 1
 slug: /fact-statement
 ---
 
+import CodeBlock from '@theme/CodeBlock';
+import factStatement from '!!raw-loader!/schema/cer/cex/fact-statement.json';
+
 # Fact Statement
 
 A place for Orcfax to describe the types/properties relevant to a
@@ -70,3 +73,9 @@ understanding.
 [prop-14]: https://schema.org/priceCurrency
 [prop-15]: https://schema.org/text
 [prop-16]: https://schema.org/url
+
+## Fact Statement Example
+
+<CodeBlock language="jsx">{factStatement}</CodeBlock>
+
+<a target="_blank" href="/schema/cer/cex/fact-statement.json" download="fact-statement.json">Download</a>

[ross-spencer]

On dates -- as this is to become a spec, when we have an approach, we might want to go through the dates and normalize them to something like `1970-01-01T00:00:00Z" so they become consistent across the examples. Might not be worth it? Open for discussion.

[Christian-MK]

On dates -- as this is to become a spec, when we have an approach, we might want to go through the dates and normalize them to something like `1970-01-01T00:00:00Z" so they become consistent across the examples. Might not be worth it? Open for discussion.

Completely agree, but I just did a quick review of rc8 and didnt see a divergence. Are we representing dates inconsistently at present?

[Christian-MK]

and then maybe something like this?

@ross-spencer
With the resulting json being added into the md file, what will be the purpose of overview.mdx?

My current understanding

• docs/Feeds/overview.md : A place to give brief descriptions for current feed types
• docs/Feeds/CER/CEX/overview.mdx : A place to describe CER feeds derived from CEXes; perhaps it links out to an explorer page that lists all feeds with this type?

[ross-spencer]

@Christian-MK sorry for the confusion, I don't think I really created overview.mdx with any particular purpose except maybe an entry point/front-page for the rest. Could be titled anything -- up to you?

I'd definitely vote to have specific json examples on their specific pages though rather than lots on one single page.

[ross-spencer]

My current understanding

docs/Feeds/overview.md : A place to give brief descriptions for current feed types

^^ seems good

docs/Feeds/CER/CEX/overview.mdx : A place to describe CER feeds derived from CEXes; perhaps it links out to an explorer page that lists all feeds with this type?

^^ not sure an overview.md and overview.mdx are needed (they satisfy the same need?)

I wouldn't couple this with the explorer, this should be focused on specification/schema not the business systems we're running as a result.

[Christian-MK]

@ross-spencer
General question re term definitions:
How should we balance maintaining the schema.org definitions vs making the definitions specific to how Orcfax is utilizing them?

Example:

hasPart: Indicates an item or CreativeWork that is part of this item, or CreativeWork
vs
hasPart: Indicates the messages and the reported values implicated in the validation record.

That example def I made up on the fly but I think it gets the point across.
So far, I have been taking the lightest approach possible, but the validation.json has several terms which we are using very specifically

[ross-spencer]

How should we balance maintaining the schema.org definitions vs making the definitions specific to how Orcfax is utilizing them?

good question.

is it easy enough to add another column with the title "canonical reference" or something, and link out to schema.org?

[Christian-MK]

add another column

I've done this for fact-statement-datum so that you can see how it looks. Let me know what you think.

Also, markdownlint doesnt like import in the first line as it expects a heading-- whats that nifty trick for forcing markdownlint to ignore a line(s)?

[ross-spencer]

@Christian-MK looks good to me (I mean, I wish there were fewer blank cells, but it represents things correctly.)

For the ignore, you can use <--markdownlint-disable--> then a subsequent enable, but since it will be on many pages you're best off adding the rule to the markdownlint,.yaml file:

diff --git a/.markdownlint.yaml b/.markdownlint.yaml
index 7aed438..28db018 100644
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -10,3 +10,4 @@ MD033: false
 MD013:
     line_length: 80
     tables: false
+MD041: false

[ross-spencer]

NB. we can resolve the conflicts on this branch before merging, let me know when it's ready to review and i can help. Looks like it's a bit of a persnickety one.

[Christian-MK]

NB. we can resolve the conflicts on this branch before merging, let me know when it's ready to review and i can help. Looks like it's a bit of a persnickety one.

Seems like you may have already done the work of sorting out the conflicts?
I believe this is now ready for your review @ross-spencer thanks for your patience.

[ross-spencer]

re: conflicts @Christian-MK

^^ I anticipate reviewing and addressing this PR tomorrow

The conflict is likely because of the merge of main into this branch -- instead it probably needed something like:

fetch --all && git rebase origin/main

To bring things into shape.

The primary option forward is just to cherry-pick the content/config commits into a new branch made from main, or move things over manually.

Not a huge task so happy to do this.

[Christian-MK]

Not a huge task so happy to do this.

Yikes, that's my bad.
Thank you for sorting this out

[ross-spencer]

Great work @Christian-MK! And merged via #35