feat: move around const & annotations

BREAKING CHANGE: meta is removed

BREAKING CHANGE: const is no longer a part of annotations

BREAKING CHANGE: drop OAS-ish validation keywords

Author: P0lip

src/accessors/__tests__/getAnnotations.spec.ts

@@ -0,0 +1,24 @@
+import { getAnnotations } from '../getAnnotations';
+
+describe('getAnnotations util', () => {
+  it('should treat example as examples', () => {
+    expect(
+      getAnnotations({
+        example: 'foo',
+      }),
+    ).toStrictEqual({
+      examples: ['foo'],
+    });
+  });
+
+  it('should prefer examples over example', () => {
+    expect(
+      getAnnotations({
+        examples: ['bar', 'baz'],
+        example: 'foo',
+      }),
+    ).toStrictEqual({
+      examples: ['bar', 'baz'],
+    });
+  });
+});

src/accessors/getAnnotations.ts

@@ -1,9 +1,16 @@
-import type { SchemaAnnotations } from '../nodes/types';
 import type { SchemaFragment } from '../types';
 import { pick } from '../utils/pick';
 
-const ANNOTATIONS: SchemaAnnotations[] = ['description', 'default', 'examples', 'const', 'x-example'];
+const ANNOTATIONS = ['description', 'default', 'examples'] as const;
+
+export type SchemaAnnotations = typeof ANNOTATIONS[number];
 
 export function getAnnotations(fragment: SchemaFragment) {
-  return pick(fragment, ANNOTATIONS);
+  const annotations = pick(fragment, ANNOTATIONS);
+  if ('example' in fragment && !Array.isArray(annotations.examples)) {
+    // example is more OAS-ish, but it's common enough to be worth supporting
+    annotations.examples = [fragment.example];
+  }
+
+  return annotations;
 }

src/accessors/getMeta.ts

@@ -2,7 +2,6 @@ import type { Dictionary } from '@stoplight/types';
 
 import { getAnnotations } from '../accessors/getAnnotations';
 import { getCombiners } from '../accessors/getCombiners';
-import { getMeta } from '../accessors/getMeta';
 import { getPrimaryType } from '../accessors/getPrimaryType';
 import { getRequired } from '../accessors/getRequired';
 import { getTypes } from '../accessors/getTypes';
@@ -13,9 +12,10 @@ import { isRegularNode, isSchemaNode } from '../guards';
 import type { SchemaFragment } from '../types';
 import { BaseNode } from './BaseNode';
 import type { ReferenceNode } from './ReferenceNode';
-import { MirroredSchemaNode, SchemaAnnotations, SchemaCombinerName, SchemaMeta, SchemaNodeKind } from './types';
+import { MirroredSchemaNode, SchemaAnnotations, SchemaCombinerName, SchemaNodeKind } from './types';
 
 export class RegularNode extends BaseNode {
+  public readonly $id: string | null;
   public readonly types: SchemaNodeKind[] | null;
   public readonly primaryType: SchemaNodeKind | null; // object (first choice) or array (second option), primitive last
   public readonly combiners: SchemaCombinerName[] | null;
@@ -28,24 +28,23 @@ export class RegularNode extends BaseNode {
 
   public children: (RegularNode | ReferenceNode | MirroredSchemaNode)[] | null | undefined;
 
-  public readonly meta: Readonly<Partial<Dictionary<unknown, SchemaMeta>>>;
   public readonly annotations: Readonly<Partial<Dictionary<unknown, SchemaAnnotations>>>;
   public readonly validations: Readonly<Dictionary<unknown>>;
 
   constructor(public readonly fragment: SchemaFragment) {
     super(fragment);
 
+    this.$id = unwrapStringOrNull('id' in fragment ? fragment.id : fragment.$id);
     this.types = getTypes(fragment);
     this.primaryType = getPrimaryType(fragment, this.types);
     this.combiners = getCombiners(fragment);
 
     this.deprecated = isDeprecated(fragment);
-    this.enum = unwrapArrayOrNull(fragment.enum);
+    this.enum = 'const' in fragment ? [fragment.const] : unwrapArrayOrNull(fragment.enum);
     this.required = getRequired(fragment.required);
     this.format = unwrapStringOrNull(fragment.format);
     this.title = unwrapStringOrNull(fragment.title);
 
-    this.meta = getMeta(fragment);
     this.annotations = getAnnotations(fragment);
     this.validations = getValidations(fragment, this.types);
 

src/nodes/RegularNode.ts

@@ -5,10 +5,11 @@ import { isNonNullable } from '../../utils';
 import { BaseNode } from '../BaseNode';
 import type { ReferenceNode } from '../ReferenceNode';
 import type { RegularNode } from '../RegularNode';
-import type { SchemaAnnotations, SchemaCombinerName, SchemaMeta, SchemaNodeKind } from '../types';
+import type { SchemaAnnotations, SchemaCombinerName, SchemaNodeKind } from '../types';
 import { MirroredReferenceNode } from './MirroredReferenceNode';
 
 export class MirroredRegularNode extends BaseNode implements RegularNode {
+  public readonly $id!: string | null;
   public readonly types!: SchemaNodeKind[] | null;
   public readonly primaryType!: SchemaNodeKind | null;
   public readonly combiners!: SchemaCombinerName[] | null;
@@ -19,7 +20,6 @@ export class MirroredRegularNode extends BaseNode implements RegularNode {
   public readonly title!: string | null;
   public readonly deprecated!: boolean;
 
-  public readonly meta!: Readonly<Partial<Dictionary<unknown, SchemaMeta>>>;
   public readonly annotations!: Readonly<Partial<Dictionary<unknown, SchemaAnnotations>>>;
   public readonly validations!: Readonly<Dictionary<unknown>>;
 

src/nodes/mirrored/MirroredRegularNode.ts

@@ -25,6 +25,4 @@ export enum SchemaCombinerName {
   OneOf = 'oneOf',
 }
 
-export type SchemaAnnotations = 'description' | 'default' | 'examples' | 'const' | 'example' | 'x-example';
-
-export type SchemaMeta = 'id' | '$schema';
+export { SchemaAnnotations } from '../accessors/getAnnotations';

src/nodes/types.ts

@@ -1,6 +1,6 @@
 import type { Dictionary } from '@stoplight/types';
 
-export function pick(target: object, keys: (string | number)[]) {
+export function pick(target: object, keys: readonly (string | number)[]) {
   const source: Dictionary<unknown, string | number> = {};
 
   for (const key of keys) {