[DMS-1183] Extend MetaEd and DMS OpenAPI for Change Queries

packages/metaed-plugin-edfi-api-schema/package.json

@@ -34,7 +34,8 @@
     "@edfi/ed-fi-model-6.1": "3.0.0",
     "@types/json-stable-stringify": "^1.2.0",
     "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1"
+    "ajv-formats": "^2.1.1",
+    "openapi-types": "^12.1.3"
   },
   "scripts": {
     "build": "npm run build:clean && npm run build:copy-non-ts && npm run build:dist",

packages/metaed-plugin-edfi-api-schema/src/enhancer/ApiSchemaBuildingEnhancer.ts

@@ -213,6 +213,7 @@ export function enhance(metaEd: MetaEdEnvironment): EnhancerResult {
     const resourceNameMapping: ResourceNameMapping = {};
     const caseInsensitiveEndpointNameMapping: CaseInsensitiveEndpointNameMapping = {};
     const abstractResources: AbstractResourceMapping = {};
+    const namespaceEdfiApiSchema: NamespaceEdfiApiSchema = namespace.data.edfiApiSchema as NamespaceEdfiApiSchema;
 
     const projectSchema: ProjectSchema = {
       projectName: namespace.projectName as MetaEdProjectName,
@@ -227,11 +228,13 @@ export function enhance(metaEd: MetaEdEnvironment): EnhancerResult {
       isExtensionProject: namespace.isExtension,
       educationOrganizationTypes: namespace.data.educationOrganizationTypes as MetaEdResourceName[],
       educationOrganizationHierarchy: namespace.data.educationOrganizationHierarchy as EducationOrganizationHierarchy,
-      domains: (namespace.data.edfiApiSchema as NamespaceEdfiApiSchema).domains,
-      openApiBaseDocuments: (namespace.data.edfiApiSchema as NamespaceEdfiApiSchema).openApiBaseDocuments,
+      domains: namespaceEdfiApiSchema.domains,
+      ...(namespace.isExtension || namespaceEdfiApiSchema.openApiBaseDocuments == null
+        ? {}
+        : { openApiBaseDocuments: namespaceEdfiApiSchema.openApiBaseDocuments }),
     };
 
-    const { apiSchema } = namespace.data.edfiApiSchema as NamespaceEdfiApiSchema;
+    const { apiSchema } = namespaceEdfiApiSchema;
     apiSchema.projectSchema = projectSchema;
 
     getEntitiesOfTypeForNamespaces([namespace], 'domainEntity').forEach((domainEntity) => {

packages/metaed-plugin-edfi-api-schema/src/enhancer/EnhancerList.ts

@@ -21,6 +21,7 @@ import { enhance as mergeCoveringFlattenedIdentityPropertyEnhancer } from './Mer
 import { enhance as jsonSchemaForInsertEnhancer } from './JsonSchemaForInsertEnhancer';
 import { enhance as commonExtensionOverrideCollectorEnhancer } from './CommonExtensionOverrideCollectorEnhancer';
 import { enhance as openApiReferenceComponentEnhancer } from './OpenApiReferenceComponentEnhancer';
+import { enhance as openApiTrackedChangeKeyFieldEnhancer } from './OpenApiTrackedChangeKeyFieldEnhancer';
 import { enhance as openApiRequestBodyComponentEnhancer } from './OpenApiRequestBodyComponentEnhancer';
 import { enhance as openApiRequestBodyCollectionComponentEnhancer } from './OpenApiRequestBodyCollectionComponentEnhancer';
 import { enhance as openApiRequestBodyCollectionComponentSubclassEnhancer } from './OpenApiRequestBodyCollectionComponentSubclassEnhancer';
@@ -75,6 +76,7 @@ export function enhancerList(): Enhancer[] {
     jsonSchemaForInsertEnhancer,
     commonExtensionOverrideCollectorEnhancer,
     openApiReferenceComponentEnhancer,
+    openApiTrackedChangeKeyFieldEnhancer,
     openApiRequestBodyComponentEnhancer,
     openApiRequestBodyCollectionComponentEnhancer,
     openApiRequestBodyCollectionComponentSubclassEnhancer,

packages/metaed-plugin-edfi-api-schema/src/enhancer/IdentityJsonPathsEnhancer.ts

@@ -36,6 +36,11 @@ export function enhance(metaEd: MetaEdEnvironment): EnhancerResult {
     (descriptor.data.edfiApiSchema as EntityApiSchemaData).identityJsonPaths = [];
   });
 
+  // SchoolYearType is modeled by a hard-coded resource schema with schoolYear as its public identity.
+  getAllEntitiesOfType(metaEd, 'schoolYearEnumeration').forEach((schoolYearEnumeration) => {
+    (schoolYearEnumeration.data.edfiApiSchema as EntityApiSchemaData).identityJsonPaths = ['$.schoolYear' as JsonPath];
+  });
+
   return {
     enhancerName: 'IdentityJsonPathsEnhancer',
     success: true,

packages/metaed-plugin-edfi-api-schema/src/enhancer/OpenApiBaseDocumentEnhancer.ts

@@ -4,21 +4,81 @@
 // See the LICENSE and NOTICES files in the project root for more information.
 
 import { type MetaEdEnvironment, type EnhancerResult, type Namespace } from '@edfi/metaed-core';
-import { ComponentsObject, Document } from '../model/OpenApiTypes';
+import { ComponentsObject, Document, Operation, PathsObject } from '../model/OpenApiTypes';
 import { NamespaceEdfiApiSchema } from '../model/Namespace';
 import { createHardcodedParameterResponses, createHardcodedComponentParameters } from './OpenApiSpecificationEnhancerBase';
 import { newSchoolYearOpenApis } from './OpenApiComponentEnhancerBase';
+import { OpenApiDocumentType, OpenApiDocumentTypeValue } from '../model/api-schema/OpenApiDocumentType';
 
 /**
- * Creates the base OpenAPI document structure without paths, schemas, or tags.
- * This structure is common to all OpenAPI documents (resources, descriptors, etc.)
+ * Creates the component object for a document type.
  */
-function createBaseOpenApiDocument(metaEd: MetaEdEnvironment, documentType: string): Document {
-  const components: ComponentsObject = {
+function createComponentsObject(documentType: OpenApiDocumentTypeValue): ComponentsObject {
+  if (documentType === OpenApiDocumentType.CHANGE_QUERIES) {
+    return {
+      schemas: {},
+      responses: {},
+      parameters: {},
+    };
+  }
+
+  return {
     schemas: {},
     responses: createHardcodedParameterResponses(),
     parameters: createHardcodedComponentParameters(),
   };
+}
+
+/**
+ * Creates the Change Queries available change versions operation.
+ */
+function createAvailableChangeVersionsOperation(): Operation {
+  return {
+    operationId: 'getAvailableChangeVersions',
+    summary: 'Retrieves the available change version range.',
+    responses: {
+      '200': {
+        description: 'The available change version range was successfully retrieved.',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              required: ['oldestChangeVersion', 'newestChangeVersion'],
+              properties: {
+                oldestChangeVersion: {
+                  type: 'integer',
+                  format: 'int64',
+                },
+                newestChangeVersion: {
+                  type: 'integer',
+                  format: 'int64',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Creates the path object for the standalone Change Queries OpenAPI document.
+ */
+function createChangeQueriesPaths(): PathsObject {
+  return {
+    '/availableChangeVersions': {
+      get: createAvailableChangeVersionsOperation(),
+    },
+  };
+}
+
+/**
+ * Creates the base OpenAPI document structure with document-specific initial paths and components.
+ * This structure is common to all OpenAPI documents (resources, descriptors, etc.)
+ */
+function createBaseOpenApiDocument(metaEd: MetaEdEnvironment, documentType: OpenApiDocumentTypeValue): Document {
+  const components: ComponentsObject = createComponentsObject(documentType);
 
   const openApiDocument: Document = {
     openapi: '3.0.0',
@@ -34,15 +94,18 @@ function createBaseOpenApiDocument(metaEd: MetaEdEnvironment, documentType: stri
         url: '',
       },
     ],
-    paths: {},
+    paths: documentType === OpenApiDocumentType.CHANGE_QUERIES ? createChangeQueriesPaths() : {},
     components,
     tags: [],
   };
 
   // Add hardcoded SchoolYearTypeReference schema only to resources document
-  if (documentType === 'resources') {
+  if (documentType === OpenApiDocumentType.RESOURCES) {
     const schoolYearOpenApis = newSchoolYearOpenApis(metaEd.minSchoolYear, metaEd.maxSchoolYear);
-    components.schemas!.EdFi_SchoolYearTypeReference = schoolYearOpenApis.schoolYearEnumerationOpenApi;
+    const { schemas } = components;
+    if (schemas != null) {
+      schemas.EdFi_SchoolYearTypeReference = schoolYearOpenApis.schoolYearEnumerationOpenApi;
+    }
   }
 
   return openApiDocument;
@@ -59,10 +122,11 @@ export function enhance(metaEd: MetaEdEnvironment): EnhancerResult {
 
     const namespaceEdfiApiSchema: NamespaceEdfiApiSchema = namespace.data.edfiApiSchema as NamespaceEdfiApiSchema;
 
-    // Create base documents for resources and descriptors
+    // Create base documents for resources, descriptors, and the standalone Change Queries fixed route.
     namespaceEdfiApiSchema.openApiBaseDocuments = {
-      resources: createBaseOpenApiDocument(metaEd, 'resources'),
-      descriptors: createBaseOpenApiDocument(metaEd, 'descriptors'),
+      [OpenApiDocumentType.RESOURCES]: createBaseOpenApiDocument(metaEd, OpenApiDocumentType.RESOURCES),
+      [OpenApiDocumentType.DESCRIPTORS]: createBaseOpenApiDocument(metaEd, OpenApiDocumentType.DESCRIPTORS),
+      [OpenApiDocumentType.CHANGE_QUERIES]: createBaseOpenApiDocument(metaEd, OpenApiDocumentType.CHANGE_QUERIES),
     };
   });