explainer.schema.json
927 lines · archify/schemas/explainer.schema.json at a406594
1{
2 "$schema": "https://json-schema.org/draft/2020-12/schema",
3 "$id": "https://github.com/tt-a1i/archify/schemas/explainer.schema.json",
4 "title": "Archify Explainer v1",
5 "type": "object",
6 "additionalProperties": false,
7 "required": [
8 "schema_version",
9 "diagram_type",
10 "meta",
11 "answer",
12 "panels",
13 "sources"
14 ],
15 "properties": {
16 "schema_version": {
17 "const": 1
18 },
19 "diagram_type": {
20 "const": "explainer"
21 },
22 "meta": {
23 "type": "object",
24 "additionalProperties": false,
25 "required": [
26 "id",
27 "title"
28 ],
29 "properties": {
30 "id": {
31 "$ref": "#/$defs/id"
32 },
33 "title": {
34 "$ref": "#/$defs/short"
35 },
36 "output": {
37 "$ref": "common.schema.json#/$defs/portableOutputPath"
38 },
39 "locale": {
40 "$ref": "common.schema.json#/$defs/locale"
41 },
42 "quality_profile": {
43 "$ref": "common.schema.json#/$defs/qualityProfile"
44 },
45 "style": {
46 "enum": [
47 "clean",
48 "editorial",
49 "product",
50 "swiss"
51 ]
52 },
53 "repository": {
54 "$ref": "common.schema.json#/$defs/repository"
55 }
56 }
57 },
58 "answer": {
59 "type": "object",
60 "additionalProperties": false,
61 "required": [
62 "summary"
63 ],
64 "properties": {
65 "summary": {
66 "$ref": "#/$defs/text"
67 },
68 "reasons": {
69 "type": "array",
70 "items": {
71 "$ref": "#/$defs/text"
72 },
73 "maxItems": 4
74 },
75 "scope": {
76 "$ref": "#/$defs/text"
77 }
78 }
79 },
80 "panels": {
81 "type": "array",
82 "items": {
83 "type": "object",
84 "additionalProperties": false,
85 "required": [
86 "id",
87 "title",
88 "blocks"
89 ],
90 "properties": {
91 "id": {
92 "$ref": "#/$defs/id"
93 },
94 "title": {
95 "$ref": "#/$defs/short"
96 },
97 "span": {
98 "type": "integer",
99 "minimum": 1,
100 "maximum": 12
101 },
102 "blocks": {
103 "type": "array",
104 "items": {
105 "$ref": "#/$defs/block"
106 },
107 "minItems": 1,
108 "maxItems": 500
109 }
110 }
111 },
112 "minItems": 1,
113 "maxItems": 500
114 },
115 "sources": {
116 "type": "array",
117 "items": {
118 "$ref": "#/$defs/source"
119 },
120 "minItems": 0,
121 "maxItems": 500
122 }
123 },
124 "$defs": {
125 "id": {
126 "type": "string",
127 "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
128 "maxLength": 100
129 },
130 "text": {
131 "type": "string",
132 "minLength": 1,
133 "maxLength": 20000
134 },
135 "short": {
136 "type": "string",
137 "minLength": 1,
138 "maxLength": 500
139 },
140 "refs": {
141 "type": "array",
142 "items": {
143 "$ref": "#/$defs/id"
144 }
145 },
146 "prose": {
147 "type": "object",
148 "additionalProperties": false,
149 "required": [
150 "id",
151 "type",
152 "text"
153 ],
154 "properties": {
155 "id": {
156 "$ref": "#/$defs/id"
157 },
158 "type": {
159 "const": "prose"
160 },
161 "text": {
162 "$ref": "#/$defs/text"
163 }
164 }
165 },
166 "list": {
167 "type": "object",
168 "additionalProperties": false,
169 "required": [
170 "id",
171 "type",
172 "items"
173 ],
174 "properties": {
175 "id": {
176 "$ref": "#/$defs/id"
177 },
178 "type": {
179 "const": "list"
180 },
181 "items": {
182 "type": "array",
183 "items": {
184 "$ref": "#/$defs/text"
185 },
186 "minItems": 1,
187 "maxItems": 500
188 },
189 "ordered": {
190 "type": "boolean"
191 },
192 "checklist": {
193 "type": "boolean"
194 }
195 }
196 },
197 "callout": {
198 "type": "object",
199 "additionalProperties": false,
200 "required": [
201 "id",
202 "type",
203 "level",
204 "text"
205 ],
206 "properties": {
207 "id": {
208 "$ref": "#/$defs/id"
209 },
210 "type": {
211 "const": "callout"
212 },
213 "level": {
214 "enum": [
215 "note",
216 "warning",
217 "open-question"
218 ]
219 },
220 "title": {
221 "$ref": "#/$defs/short"
222 },
223 "text": {
224 "$ref": "#/$defs/text"
225 }
226 }
227 },
228 "comparison": {
229 "type": "object",
230 "additionalProperties": false,
231 "required": [
232 "id",
233 "type",
234 "columns",
235 "rows"
236 ],
237 "properties": {
238 "id": {
239 "$ref": "#/$defs/id"
240 },
241 "type": {
242 "const": "comparison"
243 },
244 "labelColumn": {
245 "$ref": "#/$defs/short"
246 },
247 "columns": {
248 "type": "array",
249 "items": {
250 "$ref": "#/$defs/short"
251 },
252 "minItems": 1,
253 "maxItems": 500
254 },
255 "rows": {
256 "type": "array",
257 "items": {
258 "type": "object",
259 "additionalProperties": false,
260 "required": [
261 "id",
262 "label",
263 "cells"
264 ],
265 "properties": {
266 "id": {
267 "$ref": "#/$defs/id"
268 },
269 "label": {
270 "$ref": "#/$defs/short"
271 },
272 "cells": {
273 "type": "array",
274 "items": {
275 "type": "object",
276 "additionalProperties": false,
277 "required": [
278 "text"
279 ],
280 "properties": {
281 "text": {
282 "$ref": "#/$defs/text"
283 },
284 "assessment": {
285 "enum": [
286 "good",
287 "caution",
288 "bad"
289 ]
290 },
291 "verdict": {
292 "$ref": "#/$defs/short"
293 }
294 }
295 },
296 "minItems": 1,
297 "maxItems": 500
298 }
299 }
300 },
301 "minItems": 1,
302 "maxItems": 500
303 }
304 }
305 },
306 "facts": {
307 "type": "object",
308 "additionalProperties": false,
309 "required": [
310 "id",
311 "type",
312 "entries"
313 ],
314 "properties": {
315 "id": {
316 "$ref": "#/$defs/id"
317 },
318 "type": {
319 "const": "facts"
320 },
321 "entries": {
322 "type": "array",
323 "items": {
324 "type": "object",
325 "additionalProperties": false,
326 "required": [
327 "key",
328 "value"
329 ],
330 "properties": {
331 "key": {
332 "$ref": "#/$defs/short"
333 },
334 "value": {
335 "$ref": "#/$defs/text"
336 }
337 }
338 },
339 "minItems": 1,
340 "maxItems": 500
341 }
342 }
343 },
344 "metric": {
345 "type": "object",
346 "additionalProperties": false,
347 "required": [
348 "id",
349 "type",
350 "label"
351 ],
352 "properties": {
353 "id": {
354 "$ref": "#/$defs/id"
355 },
356 "type": {
357 "const": "metric"
358 },
359 "label": {
360 "$ref": "#/$defs/short"
361 },
362 "value": {
363 "type": "number"
364 },
365 "limit": {
366 "type": "number",
367 "exclusiveMinimum": 0
368 },
369 "unit": {
370 "$ref": "#/$defs/short"
371 },
372 "note": {
373 "$ref": "#/$defs/text"
374 },
375 "typical": {
376 "type": "boolean"
377 }
378 }
379 },
380 "steps": {
381 "type": "object",
382 "additionalProperties": false,
383 "required": [
384 "id",
385 "type",
386 "items"
387 ],
388 "properties": {
389 "id": {
390 "$ref": "#/$defs/id"
391 },
392 "type": {
393 "const": "steps"
394 },
395 "items": {
396 "type": "array",
397 "items": {
398 "type": "object",
399 "additionalProperties": false,
400 "required": [
401 "id",
402 "text"
403 ],
404 "properties": {
405 "id": {
406 "$ref": "#/$defs/id"
407 },
408 "text": {
409 "$ref": "#/$defs/text"
410 },
411 "detail": {
412 "$ref": "#/$defs/text"
413 },
414 "target": {
415 "type": "object",
416 "additionalProperties": false,
417 "required": [
418 "diagram"
419 ],
420 "properties": {
421 "diagram": {
422 "$ref": "#/$defs/id"
423 },
424 "node": {
425 "$ref": "#/$defs/id"
426 },
427 "route": {
428 "type": "array",
429 "prefixItems": [
430 {
431 "$ref": "#/$defs/id"
432 },
433 {
434 "$ref": "#/$defs/id"
435 }
436 ],
437 "items": false,
438 "minItems": 2,
439 "maxItems": 2
440 },
441 "edges": {
442 "$ref": "#/$defs/refs"
443 }
444 }
445 }
446 }
447 },
448 "minItems": 1,
449 "maxItems": 500
450 }
451 }
452 },
453 "diagram": {
454 "type": "object",
455 "additionalProperties": false,
456 "required": [
457 "id",
458 "type",
459 "diagramType"
460 ],
461 "properties": {
462 "id": {
463 "$ref": "#/$defs/id"
464 },
465 "type": {
466 "const": "diagram"
467 },
468 "diagramType": {
469 "enum": [
470 "architecture",
471 "workflow",
472 "sequence",
473 "dataflow",
474 "lifecycle",
475 "erd",
476 "class",
477 "tree",
478 "timeline",
479 "waterfall"
480 ]
481 },
482 "spec": {
483 "type": "object"
484 },
485 "source": {
486 "$ref": "#/$defs/short"
487 },
488 "nodeSources": {
489 "type": "object",
490 "propertyNames": {
491 "$ref": "#/$defs/id"
492 },
493 "additionalProperties": {
494 "$ref": "#/$defs/id"
495 },
496 "maxProperties": 500
497 },
498 "changes": {
499 "type": "array",
500 "items": {
501 "type": "object",
502 "additionalProperties": false,
503 "required": [
504 "target",
505 "change"
506 ],
507 "properties": {
508 "target": {
509 "$ref": "#/$defs/id"
510 },
511 "change": {
512 "enum": [
513 "added",
514 "removed",
515 "modified"
516 ]
517 }
518 }
519 },
520 "minItems": 1,
521 "maxItems": 500
522 }
523 },
524 "oneOf": [
525 {
526 "properties": {
527 "spec": {}
528 },
529 "required": [
530 "spec"
531 ]
532 },
533 {
534 "properties": {
535 "source": {}
536 },
537 "required": [
538 "source"
539 ]
540 }
541 ]
542 },
543 "code": {
544 "type": "object",
545 "additionalProperties": false,
546 "required": [
547 "id",
548 "type",
549 "source"
550 ],
551 "properties": {
552 "id": {
553 "$ref": "#/$defs/id"
554 },
555 "type": {
556 "const": "code"
557 },
558 "source": {
559 "$ref": "#/$defs/id"
560 },
561 "language": {
562 "$ref": "#/$defs/short"
563 }
564 }
565 },
566 "snippet": {
567 "type": "object",
568 "additionalProperties": false,
569 "required": [
570 "id",
571 "type",
572 "text"
573 ],
574 "properties": {
575 "id": {
576 "$ref": "#/$defs/id"
577 },
578 "type": {
579 "const": "snippet"
580 },
581 "language": {
582 "$ref": "#/$defs/short"
583 },
584 "title": {
585 "$ref": "#/$defs/short"
586 },
587 "text": {
588 "$ref": "#/$defs/text"
589 }
590 }
591 },
592 "diff": {
593 "type": "object",
594 "additionalProperties": false,
595 "required": [
596 "id",
597 "type",
598 "text"
599 ],
600 "properties": {
601 "id": {
602 "$ref": "#/$defs/id"
603 },
604 "type": {
605 "const": "diff"
606 },
607 "text": {
608 "$ref": "#/$defs/text"
609 },
610 "caption": {
611 "$ref": "#/$defs/text"
612 }
613 }
614 },
615 "image": {
616 "type": "object",
617 "additionalProperties": false,
618 "required": [
619 "id",
620 "type",
621 "path",
622 "alt"
623 ],
624 "properties": {
625 "id": {
626 "$ref": "#/$defs/id"
627 },
628 "type": {
629 "const": "image"
630 },
631 "path": {
632 "$ref": "#/$defs/short"
633 },
634 "alt": {
635 "$ref": "#/$defs/text"
636 },
637 "caption": {
638 "$ref": "#/$defs/text"
639 }
640 }
641 },
642 "block": {
643 "type": "object",
644 "required": [
645 "type"
646 ],
647 "properties": {
648 "type": {
649 "enum": [
650 "prose",
651 "list",
652 "callout",
653 "comparison",
654 "facts",
655 "metric",
656 "steps",
657 "diagram",
658 "code",
659 "snippet",
660 "chart",
661 "diff",
662 "image"
663 ]
664 }
665 },
666 "allOf": [
667 {
668 "if": {
669 "properties": {
670 "type": {
671 "const": "prose"
672 }
673 }
674 },
675 "then": {
676 "$ref": "#/$defs/prose"
677 }
678 },
679 {
680 "if": {
681 "properties": {
682 "type": {
683 "const": "list"
684 }
685 }
686 },
687 "then": {
688 "$ref": "#/$defs/list"
689 }
690 },
691 {
692 "if": {
693 "properties": {
694 "type": {
695 "const": "callout"
696 }
697 }
698 },
699 "then": {
700 "$ref": "#/$defs/callout"
701 }
702 },
703 {
704 "if": {
705 "properties": {
706 "type": {
707 "const": "comparison"
708 }
709 }
710 },
711 "then": {
712 "$ref": "#/$defs/comparison"
713 }
714 },
715 {
716 "if": {
717 "properties": {
718 "type": {
719 "const": "facts"
720 }
721 }
722 },
723 "then": {
724 "$ref": "#/$defs/facts"
725 }
726 },
727 {
728 "if": {
729 "properties": {
730 "type": {
731 "const": "metric"
732 }
733 }
734 },
735 "then": {
736 "$ref": "#/$defs/metric"
737 }
738 },
739 {
740 "if": {
741 "properties": {
742 "type": {
743 "const": "steps"
744 }
745 }
746 },
747 "then": {
748 "$ref": "#/$defs/steps"
749 }
750 },
751 {
752 "if": {
753 "properties": {
754 "type": {
755 "const": "diagram"
756 }
757 }
758 },
759 "then": {
760 "$ref": "#/$defs/diagram"
761 }
762 },
763 {
764 "if": {
765 "properties": {
766 "type": {
767 "const": "code"
768 }
769 }
770 },
771 "then": {
772 "$ref": "#/$defs/code"
773 }
774 },
775 {
776 "if": {
777 "properties": {
778 "type": {
779 "const": "snippet"
780 }
781 }
782 },
783 "then": {
784 "$ref": "#/$defs/snippet"
785 }
786 },
787 {
788 "if": {
789 "properties": {
790 "type": {
791 "const": "chart"
792 }
793 }
794 },
795 "then": {
796 "$ref": "#/$defs/chart"
797 }
798 },
799 {
800 "if": {
801 "properties": {
802 "type": {
803 "const": "diff"
804 }
805 }
806 },
807 "then": {
808 "$ref": "#/$defs/diff"
809 }
810 },
811 {
812 "if": {
813 "properties": {
814 "type": {
815 "const": "image"
816 }
817 }
818 },
819 "then": {
820 "$ref": "#/$defs/image"
821 }
822 }
823 ]
824 },
825 "source": {
826 "type": "object",
827 "additionalProperties": false,
828 "required": [
829 "id",
830 "title"
831 ],
832 "properties": {
833 "id": {
834 "$ref": "#/$defs/id"
835 },
836 "title": {
837 "$ref": "#/$defs/text"
838 },
839 "url": {
840 "type": "string",
841 "minLength": 1
842 },
843 "path": {
844 "$ref": "#/$defs/short"
845 },
846 "lines": {
847 "type": "array",
848 "prefixItems": [
849 {
850 "type": "integer",
851 "minimum": 1
852 },
853 {
854 "type": "integer",
855 "minimum": 1
856 }
857 ],
858 "items": false,
859 "minItems": 2,
860 "maxItems": 2
861 },
862 "revision": {
863 "type": "string",
864 "pattern": "^[a-fA-F0-9]{40}$"
865 }
866 }
867 },
868 "chart": {
869 "type": "object",
870 "additionalProperties": false,
871 "required": [
872 "id",
873 "type"
874 ],
875 "properties": {
876 "id": {
877 "$ref": "#/$defs/id"
878 },
879 "type": {
880 "const": "chart"
881 },
882 "title": {
883 "$ref": "#/$defs/short"
884 },
885 "text": {
886 "$ref": "#/$defs/text"
887 },
888 "data": {
889 "type": "object",
890 "additionalProperties": false,
891 "required": [
892 "path",
893 "kind",
894 "x",
895 "y"
896 ],
897 "properties": {
898 "path": {
899 "$ref": "#/$defs/short"
900 },
901 "kind": {
902 "enum": [
903 "bar",
904 "line",
905 "pie"
906 ]
907 },
908 "x": {
909 "$ref": "#/$defs/short"
910 },
911 "y": {
912 "type": "array",
913 "items": {
914 "$ref": "#/$defs/short"
915 },
916 "minItems": 1,
917 "maxItems": 6
918 },
919 "unit": {
920 "$ref": "#/$defs/short"
921 }
922 }
923 }
924 }
925 }
926 }
927}