Merge pull request #1283 from joshunrau/json-schema

refactor instrument schemas and add JSON schema to docs for all instrument types and languages

Author: joshunrau

apps/outreach/package.json

@@ -18,7 +18,8 @@
     "lodash-es": "workspace:lodash-es__4.x@*",
     "mdast-util-to-string": "^4.0.0",
     "reading-time": "^1.5.0",
-    "tailwind-merge": "^2.6.0"
+    "tailwind-merge": "^2.6.0",
+    "zod": "workspace:zod__3.x@*"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.4",

apps/outreach/src/components/docs/InstrumentSchemas.astro

@@ -0,0 +1,17 @@
+---
+import { getSchemaProps } from '@/lib/instrument-schemas';
+
+const schemaProps = getSchemaProps();
+---
+
+<ul>
+  {
+    schemaProps.map(({ meta, params }) => (
+      <li>
+        <a download href={`/resources/schemas/${params.kind}-instrument-${params.lang}.json`}>
+          {meta.displayName}
+        </a>
+      </li>
+    ))
+  }
+</ul>

apps/outreach/src/components/docs/Licenses.astro

@@ -40,7 +40,7 @@ const proprietaryLicenses = Array.from(licenses.entries())
 <div class="space-y-8">
   <section>
     <h3>Open Source Licenses (Approved)</h3>
-    <p class="mb-4 text-slate-700">
+    <p class="mb-4 text-slate-700 dark:text-slate-300">
       The following licenses are pre-approved for direct inclusion in the Open Data Capture repository and public
       distribution:
     </p>
@@ -61,11 +61,13 @@ const proprietaryLicenses = Array.from(licenses.entries())
         ))
       }
     </ul>
-    <p class="text-slate-700">Please note that instruments in the public domain instruments are also permitted.</p>
+    <p class="text-slate-700 dark:text-slate-300">
+      Please note that instruments in the public domain instruments are also permitted.
+    </p>
   </section>
   <section>
     <h3>Open Source Licenses (Non-Approved)</h3>
-    <p class="mb-4 text-slate-700">
+    <p class="text-slate-70 dark:text-slate-3000 mb-4">
       These open source licenses are acceptable for public distribution, but due to various clauses are not able to be
       included directly in the Open Data Capture repository.
     </p>
@@ -89,7 +91,7 @@ const proprietaryLicenses = Array.from(licenses.entries())
   </section>
   <section>
     <h3>Open Source Licenses (Review Required)</h3>
-    <p class="mb-4 text-slate-700">
+    <p class="mb-4 text-slate-700 dark:text-slate-300">
       The following licenses are considered open source, but have not been reviewed by our team.
     </p>
     <ul class="tracking-tight">
@@ -112,7 +114,7 @@ const proprietaryLicenses = Array.from(licenses.entries())
   </section>
   <section>
     <h3>Proprietary and Non-Free Licenses</h3>
-    <p class="mb-4 text-slate-700">
+    <p class="mb-4 text-slate-700 dark:text-slate-300">
       These licenses may not be published publicly by our team. This list includes non-free licenses, as well as any
       licenses with restrictions on commercial use.
     </p>

apps/outreach/src/lib/instrument-schemas.ts

@@ -0,0 +1,34 @@
+import type { InstrumentLanguage } from '@opendatacapture/runtime-core';
+import { capitalize } from 'lodash-es';
+
+const LANGUAGE_NAMES = {
+  en: 'English',
+  fr: 'French'
+};
+
+export const SCHEMA_KINDS = ['form', 'interactive', 'series', 'any'] as const;
+
+export const SCHEMA_LANGUAGES = ['en', 'fr', ['en', 'fr']] as const satisfies InstrumentLanguage[];
+
+export function getSchemaProps() {
+  return SCHEMA_KINDS.flatMap((kind) => {
+    return SCHEMA_LANGUAGES.map((language) => {
+      let displayLanguage: string;
+      if (typeof language === 'string') {
+        displayLanguage = LANGUAGE_NAMES[language];
+      } else {
+        displayLanguage = language.map((language) => LANGUAGE_NAMES[language]).join('/');
+      }
+      return {
+        meta: {
+          displayName: `${capitalize(kind)} Instrument (${displayLanguage})`,
+          language: language
+        },
+        params: {
+          kind,
+          lang: Array.isArray(language) ? language.join('-') : language
+        }
+      };
+    });
+  });
+}

apps/outreach/src/pages/resources/schemas/[kind]-instrument-[lang].json.ts

@@ -0,0 +1,31 @@
+import {
+  $$AnyInstrument,
+  $$FormInstrument,
+  $$InteractiveInstrument,
+  $$SeriesInstrument
+} from '@opendatacapture/schemas/instrument';
+import type { APIRoute, GetStaticPaths, InferGetStaticParamsType, InferGetStaticPropsType } from 'astro';
+import z from 'zod/v4';
+
+import { getSchemaProps } from '@/lib/instrument-schemas';
+
+type Params = InferGetStaticParamsType<typeof getStaticPaths>;
+
+type Props = InferGetStaticPropsType<typeof getStaticPaths>;
+
+export const getStaticPaths = (() => {
+  const schemaFactories = {
+    any: $$AnyInstrument,
+    form: $$FormInstrument,
+    interactive: $$InteractiveInstrument,
+    series: $$SeriesInstrument
+  } as const;
+  return getSchemaProps().map(({ meta, params }) => ({
+    params,
+    props: { schema: z.toJSONSchema(schemaFactories[params.kind](meta.language)) }
+  }));
+}) satisfies GetStaticPaths;
+
+export const GET: APIRoute<Props, Params> = ({ props }) => {
+  return new Response(JSON.stringify(props.schema, null, 2));
+};

docs/en/5-reference/5.9-instrument-schemas.mdx

@@ -0,0 +1,12 @@
+---
+title: Instrument Schemas (JSON)
+slug: en/docs/reference/instrument-schemas
+sidebar:
+  order: 9
+---
+
+import InstrumentSchemas from '@/components/docs/InstrumentSchemas.astro';
+
+While ODC primarily uses Zod for instrument schemas, we provide JSON Schema versions for reference and interoperability with non-TypeScript tools. While these schemas are technically accurate, certain properties that cannot be represented in JSON (such as functions) will default to accepting any value. These versions can be used for building static forms or external integrations. You can find the available schemas for all instrument types and languages below.
+
+<InstrumentSchemas />