feat(domain): sheet document schema v2 — references registry, review_status, vertebral count_range; SQL gate + pgTAP 008
This commit is contained in:
1 parent
6c5b2b7754
commit
3dbbfdf1df
19 files changed
+474
-71
No files matched your search
@@ -27,6 +27,7 @@ export function createEmptySheetDocument(
|
||||
scope_disclaimer: {},
|
||||
attribution: { authors: [], license: null, notes: null },
|
||||
vertebral_config: { regions: [] },
|
||||
references: [],
|
||||
categories: [],
|
||||
views: [
|
||||
{
|
||||
|
||||
@@ -1,16 +1,21 @@
|
||||
import { z } from 'zod'
|
||||
|
||||
/**
|
||||
* Canonical anatomical sheet document, schema_version 1.
|
||||
* Canonical anatomical sheet document, schema_version 2.
|
||||
*
|
||||
* Shape contract of docs/development/ANATOMICAL_SHEET_MODEL.md §2. Every
|
||||
* object is strict: a canonical document must not silently carry fields no
|
||||
* version of the schema defines. Cross-references (view ids, zone ids…) are
|
||||
* checked by validateSheetDocument, not here, so a draft with dangling
|
||||
* references can still be saved.
|
||||
* version of the schema defines. Cross-references (view ids, zone ids,
|
||||
* reference ids…) are checked by validateSheetDocument, not here, so a
|
||||
* draft with dangling references can still be saved.
|
||||
*
|
||||
* Version 2 (Step 4c): shared bibliographic `references` registry cited by
|
||||
* `reference_ids`, `review_status` on findings and annotations, optional
|
||||
* `count_range` on vertebral regions. No version 1 document was ever
|
||||
* published, so version 1 is not read any more.
|
||||
*/
|
||||
|
||||
export const SHEET_DOCUMENT_SCHEMA_VERSION = 1
|
||||
export const SHEET_DOCUMENT_SCHEMA_VERSION = 2
|
||||
|
||||
/** Ids are never derived from labels, so translations never move them. */
|
||||
export const STABLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/
|
||||
@@ -30,11 +35,29 @@ export const LocalizedOptionalTextSchema = z
|
||||
.object({ fr: z.string().optional(), en: z.string().optional() })
|
||||
.strict()
|
||||
|
||||
/**
|
||||
* How far the sheet content was checked against references. `inherited` =
|
||||
* taken over from a previous source without review; `reviewed` = checked
|
||||
* and cited; `to_confirm` = changed or added on documented grounds, still
|
||||
* awaiting a professional's confirmation.
|
||||
*/
|
||||
export const ReviewStatusSchema = z.enum(['inherited', 'reviewed', 'to_confirm'])
|
||||
|
||||
const CountRangeSchema = z
|
||||
.object({ min: z.number().int().min(1), max: z.number().int().min(1) })
|
||||
.strict()
|
||||
|
||||
/**
|
||||
* `count` is the usual number of vertebrae (what the picker shows by
|
||||
* default); `count_range` states the documented individual variation so a
|
||||
* report may record a vertebra beyond the usual count. Null = no variation.
|
||||
*/
|
||||
export const VertebralRegionSchema = z
|
||||
.object({
|
||||
code: RegionCodeSchema,
|
||||
name: LocalizedTextSchema,
|
||||
count: z.number().int().min(1),
|
||||
count_range: CountRangeSchema.nullable().default(null),
|
||||
})
|
||||
.strict()
|
||||
|
||||
@@ -125,6 +148,7 @@ const annotationCommon = {
|
||||
category_id: StableIdSchema,
|
||||
laterality: LateralitySchema,
|
||||
geometry: GeometrySchema.nullable(),
|
||||
review_status: ReviewStatusSchema.default('inherited'),
|
||||
}
|
||||
|
||||
/** Observable annotations link to findings through one explicit field. */
|
||||
@@ -165,15 +189,24 @@ const HttpUrlSchema = z
|
||||
.url()
|
||||
.refine((url) => /^https?:\/\//i.test(url), 'http(s) URL expected')
|
||||
|
||||
export const SourceRefSchema = z
|
||||
/**
|
||||
* One bibliographic reference, declared once in the document and cited by
|
||||
* id from any number of findings (an anatomy atlas backs hundreds of
|
||||
* entries). `citation` is the human-readable form (author, title, edition,
|
||||
* year, publisher or journal, location in the work when known).
|
||||
*/
|
||||
export const ReferenceSchema = z
|
||||
.object({
|
||||
type: z.enum(['manual', 'journal', 'database', 'web']),
|
||||
id: StableIdSchema,
|
||||
type: z.enum(['book', 'journal', 'standard', 'legal', 'web', 'manual']),
|
||||
citation: z.string().min(1),
|
||||
url: HttpUrlSchema.optional(),
|
||||
url: HttpUrlSchema.nullable().default(null),
|
||||
doi: z.string().min(1).nullable().default(null),
|
||||
})
|
||||
.strict()
|
||||
|
||||
export type SourceRef = z.infer<typeof SourceRefSchema>
|
||||
export type Reference = z.infer<typeof ReferenceSchema>
|
||||
export type ReviewStatus = z.infer<typeof ReviewStatusSchema>
|
||||
export type LocalizedText = z.infer<typeof LocalizedTextSchema>
|
||||
export type LocalizedOptionalText = z.infer<typeof LocalizedOptionalTextSchema>
|
||||
|
||||
@@ -183,7 +216,8 @@ export interface FindingNode {
|
||||
name: LocalizedText
|
||||
description: LocalizedOptionalText
|
||||
requires_vet_referral: boolean
|
||||
sources: SourceRef[]
|
||||
reference_ids: string[]
|
||||
review_status: ReviewStatus
|
||||
children: FindingNode[]
|
||||
}
|
||||
|
||||
@@ -193,7 +227,8 @@ export interface FindingNodeInput {
|
||||
name: LocalizedText
|
||||
description?: LocalizedOptionalText
|
||||
requires_vet_referral?: boolean
|
||||
sources?: SourceRef[]
|
||||
reference_ids?: string[]
|
||||
review_status?: ReviewStatus
|
||||
children?: FindingNodeInput[]
|
||||
}
|
||||
|
||||
@@ -208,7 +243,8 @@ export const FindingNodeSchema: z.ZodType<
|
||||
name: LocalizedTextSchema,
|
||||
description: LocalizedOptionalTextSchema.default({}),
|
||||
requires_vet_referral: z.boolean().default(false),
|
||||
sources: z.array(SourceRefSchema).default([]),
|
||||
reference_ids: z.array(StableIdSchema).default([]),
|
||||
review_status: ReviewStatusSchema.default('inherited'),
|
||||
children: z.array(FindingNodeSchema).default([]),
|
||||
})
|
||||
.strict(),
|
||||
@@ -228,6 +264,8 @@ export const FindingCategorySchema = z
|
||||
kind: FindingCategoryKindSchema,
|
||||
name: LocalizedTextSchema,
|
||||
description: LocalizedOptionalTextSchema.default({}),
|
||||
reference_ids: z.array(StableIdSchema).default([]),
|
||||
review_status: ReviewStatusSchema.default('inherited'),
|
||||
children: z.array(FindingNodeSchema),
|
||||
})
|
||||
.strict()
|
||||
@@ -261,6 +299,7 @@ export const AnatomicalSheetDocumentSchema = z
|
||||
scope_disclaimer: LocalizedOptionalTextSchema,
|
||||
attribution: AttributionSchema,
|
||||
vertebral_config: VertebralConfigSchema,
|
||||
references: z.array(ReferenceSchema),
|
||||
categories: z.array(AnnotationCategorySchema),
|
||||
views: z.array(SheetViewSchema),
|
||||
annotations: z.array(AnnotationSchema),
|
||||
|
||||
@@ -3,6 +3,7 @@ import type {
|
||||
Annotation,
|
||||
FindingNode,
|
||||
SheetView,
|
||||
VertebralRegion,
|
||||
} from './schema'
|
||||
|
||||
/**
|
||||
@@ -32,6 +33,7 @@ type DetailView = Extract<SheetView, { kind: 'detail' }>
|
||||
/** A sibling level of the finding tree: categories or node children. */
|
||||
interface FindingLevelItem {
|
||||
id: string
|
||||
reference_ids: readonly string[]
|
||||
children: readonly FindingNode[]
|
||||
}
|
||||
|
||||
@@ -372,6 +374,69 @@ const checkFindingZonesReferenced: Rule = (doc) => {
|
||||
)
|
||||
}
|
||||
|
||||
const checkReferenceIdsUnique: Rule = (doc) =>
|
||||
duplicateIssues(
|
||||
doc.references.map((reference) => reference.id),
|
||||
'reference.id.duplicate',
|
||||
(index) => `references[${index}].id`,
|
||||
)
|
||||
|
||||
/** A citation must point at a declared reference, at every depth. */
|
||||
function citationIssues(
|
||||
nodes: readonly FindingLevelItem[],
|
||||
path: string,
|
||||
known: ReadonlySet<string>,
|
||||
): SheetIssue[] {
|
||||
return nodes.flatMap((node, index) => {
|
||||
const own = node.reference_ids.flatMap((id, refIndex) =>
|
||||
known.has(id)
|
||||
? []
|
||||
: [
|
||||
error(
|
||||
'finding.reference.missing',
|
||||
`${path}[${index}].reference_ids[${refIndex}]`,
|
||||
`Reference "${id}" is not declared in references`,
|
||||
),
|
||||
],
|
||||
)
|
||||
const nested = citationIssues(
|
||||
node.children,
|
||||
`${path}[${index}].children`,
|
||||
known,
|
||||
)
|
||||
return [...own, ...nested]
|
||||
})
|
||||
}
|
||||
|
||||
const checkFindingReferences: Rule = (doc) => {
|
||||
const known = new Set(doc.references.map((reference) => reference.id))
|
||||
return doc.finding_zones.flatMap((zone, index) =>
|
||||
citationIssues(
|
||||
zone.categories,
|
||||
`finding_zones[${index}].categories`,
|
||||
known,
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
/** The usual count must sit inside the documented variation. */
|
||||
function countRangeIssue(region: VertebralRegion, index: number): SheetIssue[] {
|
||||
const range = region.count_range
|
||||
if (range === null) return []
|
||||
if (range.min <= region.count && region.count <= range.max) return []
|
||||
return [
|
||||
error(
|
||||
'region.count_range.invalid',
|
||||
`vertebral_config.regions[${index}].count_range`,
|
||||
`Region "${region.code}": count ${region.count} outside ` +
|
||||
`${range.min}–${range.max}`,
|
||||
),
|
||||
]
|
||||
}
|
||||
|
||||
const checkRegionCountRanges: Rule = (doc) =>
|
||||
doc.vertebral_config.regions.flatMap(countRangeIssue)
|
||||
|
||||
const RULES: readonly Rule[] = [
|
||||
checkMainViewCount,
|
||||
checkViewIdsUnique,
|
||||
@@ -391,6 +456,9 @@ const RULES: readonly Rule[] = [
|
||||
checkFindingZoneIdsUnique,
|
||||
checkFindingSiblings,
|
||||
checkFindingZonesReferenced,
|
||||
checkReferenceIdsUnique,
|
||||
checkFindingReferences,
|
||||
checkRegionCountRanges,
|
||||
]
|
||||
|
||||
/** Lists every integrity issue of a shape-valid document. */
|
||||
|
||||
@@ -50,7 +50,7 @@ describe('AnatomicalSheetDocumentSchema', () => {
|
||||
],
|
||||
['a stable id with an accent', (d) => set(d, ['categories', 0, 'id'], 'É')],
|
||||
['an empty stable id', (d) => set(d, ['finding_zones', 0, 'id'], '')],
|
||||
['schema_version 2', (d) => set(d, ['schema_version'], 2)],
|
||||
['schema_version 1', (d) => set(d, ['schema_version'], 1)],
|
||||
[
|
||||
'a non-uuid svg_asset_id',
|
||||
(d) => set(d, ['views', 0, 'svg_asset_id'], 'horse'),
|
||||
@@ -85,23 +85,21 @@ describe('AnatomicalSheetDocumentSchema', () => {
|
||||
(d) => set(d, ['annotations', 3, 'finding_zone_id'], 'hip'),
|
||||
],
|
||||
[
|
||||
'a javascript: source url',
|
||||
'a javascript: reference url',
|
||||
(d) => set(d, ['references', 0, 'url'], 'javascript:alert(1)'),
|
||||
],
|
||||
[
|
||||
'a reference type foo',
|
||||
(d) => set(d, ['references', 0, 'type'], 'foo'),
|
||||
],
|
||||
[
|
||||
'a review_status foo',
|
||||
(d) => set(d, ['annotations', 0, 'review_status'], 'foo'),
|
||||
],
|
||||
[
|
||||
'a count_range with min 0',
|
||||
(d) =>
|
||||
set(
|
||||
d,
|
||||
[
|
||||
'finding_zones',
|
||||
0,
|
||||
'categories',
|
||||
2,
|
||||
'children',
|
||||
0,
|
||||
'sources',
|
||||
0,
|
||||
'url',
|
||||
],
|
||||
'javascript:alert(1)',
|
||||
),
|
||||
set(d, ['vertebral_config', 'regions', 4, 'count_range', 'min'], 0),
|
||||
],
|
||||
[
|
||||
'a finding category kind foo',
|
||||
@@ -136,13 +134,15 @@ describe('FindingNodeSchema defaults', () => {
|
||||
})
|
||||
expect(node.description).toEqual({})
|
||||
expect(node.requires_vet_referral).toBe(false)
|
||||
expect(node.sources).toEqual([])
|
||||
expect(node.reference_ids).toEqual([])
|
||||
expect(node.review_status).toBe('inherited')
|
||||
expect(node.children[0]).toEqual({
|
||||
id: 'flexion',
|
||||
name: { fr: 'Flexion', en: 'Flexion' },
|
||||
description: {},
|
||||
requires_vet_referral: false,
|
||||
sources: [],
|
||||
reference_ids: [],
|
||||
review_status: 'inherited',
|
||||
children: [],
|
||||
})
|
||||
})
|
||||
@@ -152,7 +152,13 @@ describe('FindingNodeSchema defaults', () => {
|
||||
const lameness = doc.finding_zones[0].categories[1].children[0]
|
||||
expect(lameness.requires_vet_referral).toBe(true)
|
||||
const trauma = doc.finding_zones[0].categories[2].children[0]
|
||||
expect(trauma.sources).toHaveLength(1)
|
||||
expect(trauma.reference_ids).toEqual(['legacy-catalog'])
|
||||
expect(doc.vertebral_config.regions[4].count_range).toEqual({
|
||||
min: 15,
|
||||
max: 21,
|
||||
})
|
||||
expect(doc.vertebral_config.regions[0].count_range).toBeNull()
|
||||
expect(doc.annotations[0].review_status).toBe('inherited')
|
||||
})
|
||||
|
||||
it('does not add default keys to the lean input', () => {
|
||||
|
||||
@@ -32,6 +32,7 @@ function point(id: string, fields: Partial<Annotation> = {}): Annotation {
|
||||
category_id: 'articulations',
|
||||
laterality: 'bilateral',
|
||||
geometry: null,
|
||||
review_status: 'inherited',
|
||||
name: { fr: id, en: id },
|
||||
finding_zone_id: 'hip',
|
||||
vertebral_region_code: null,
|
||||
@@ -47,6 +48,7 @@ function trigger(id: string, viewId: string, opensViewId: string) {
|
||||
category_id: 'cadrans-du-crane',
|
||||
laterality: 'unpaired',
|
||||
geometry: null,
|
||||
review_status: 'inherited',
|
||||
name: null,
|
||||
opens_view_id: opensViewId,
|
||||
} satisfies Annotation
|
||||
@@ -284,6 +286,49 @@ describe('integrity rules (one mutation per code)', () => {
|
||||
expect(issuesOf(doc)).toEqual([])
|
||||
})
|
||||
|
||||
it('reference.id.duplicate', () => {
|
||||
const doc = mutated((d) => {
|
||||
d.references.push(structuredClone(d.references[0]))
|
||||
})
|
||||
expect(issuesOf(doc)).toEqual([
|
||||
['reference.id.duplicate', 'references[1].id'],
|
||||
])
|
||||
})
|
||||
|
||||
it('finding.reference.missing on a category and on a nested node', () => {
|
||||
const doc = mutated((d) => {
|
||||
const hip = d.finding_zones[0].categories
|
||||
hip[0].reference_ids = ['nav-2017']
|
||||
hip[0].children[0].children[0].reference_ids = ['legacy-catalog', 'x']
|
||||
})
|
||||
expect(issuesOf(doc)).toEqual([
|
||||
[
|
||||
'finding.reference.missing',
|
||||
'finding_zones[0].categories[0].reference_ids[0]',
|
||||
],
|
||||
[
|
||||
'finding.reference.missing',
|
||||
'finding_zones[0].categories[0].children[0].children[0].reference_ids[1]',
|
||||
],
|
||||
])
|
||||
})
|
||||
|
||||
it('region.count_range.invalid when count sits outside the range', () => {
|
||||
const doc = mutated((d) => {
|
||||
d.vertebral_config.regions[4].count_range = { min: 19, max: 21 }
|
||||
})
|
||||
expect(issuesOf(doc)).toEqual([
|
||||
['region.count_range.invalid', 'vertebral_config.regions[4].count_range'],
|
||||
])
|
||||
})
|
||||
|
||||
it('region.count_range accepts count on the bounds', () => {
|
||||
const doc = mutated((d) => {
|
||||
d.vertebral_config.regions[4].count_range = { min: 18, max: 18 }
|
||||
})
|
||||
expect(issuesOf(doc)).toEqual([])
|
||||
})
|
||||
|
||||
it('finding_zone.unreferenced is a warning', () => {
|
||||
const doc = mutated((d) => {
|
||||
d.finding_zones.push({
|
||||
|
||||
+15
-11
@@ -102,15 +102,7 @@ const HIP_ZONE = {
|
||||
{
|
||||
...ANAMNESIS,
|
||||
children: [
|
||||
{
|
||||
...TRAUMA,
|
||||
sources: [
|
||||
{
|
||||
type: 'manual',
|
||||
citation: 'Legacy equine catalog (pathologies.json)',
|
||||
},
|
||||
],
|
||||
},
|
||||
{ ...TRAUMA, reference_ids: ['legacy-catalog'] },
|
||||
],
|
||||
},
|
||||
],
|
||||
@@ -273,7 +265,7 @@ const SPHENOID_ZONE = {
|
||||
} satisfies AnatomicalSheetDocumentInput['finding_zones'][number]
|
||||
|
||||
const HORSE_SLICE_INPUT: AnatomicalSheetDocumentInput = {
|
||||
schema_version: 1,
|
||||
schema_version: 2,
|
||||
species_id: 'equine',
|
||||
name: { fr: 'Cheval (extrait)', en: 'Horse (slice)' },
|
||||
description: {
|
||||
@@ -294,9 +286,21 @@ const HORSE_SLICE_INPUT: AnatomicalSheetDocumentInput = {
|
||||
{ code: 'T', name: { fr: 'Thoraciques', en: 'Thoracic' }, count: 18 },
|
||||
{ code: 'L', name: { fr: 'Lombaires', en: 'Lumbar' }, count: 6 },
|
||||
{ code: 'S', name: { fr: 'Sacrées', en: 'Sacral' }, count: 5 },
|
||||
{ code: 'Cd', name: { fr: 'Caudales', en: 'Caudal' }, count: 18 },
|
||||
{
|
||||
code: 'Cd',
|
||||
name: { fr: 'Caudales', en: 'Caudal' },
|
||||
count: 18,
|
||||
count_range: { min: 15, max: 21 },
|
||||
},
|
||||
],
|
||||
},
|
||||
references: [
|
||||
{
|
||||
id: 'legacy-catalog',
|
||||
type: 'manual',
|
||||
citation: 'Legacy equine catalog (pathologies.json, schema 2.0)',
|
||||
},
|
||||
],
|
||||
categories: [
|
||||
{
|
||||
id: 'articulations',
|
||||
|
||||
Reference in new issue
Block a user