feat: json-schema updates\nfeat: new route proposal

2026-01-20 00:23:03 +00:00 · 2023-11-01 14:31:12 +01:00
parent 8466976b3c
commit 0de613969e
20 changed files with 327 additions and 131 deletions
--- a/packages/core/src/elasticsearch.ts
+++ b/packages/core/src/elasticsearch.ts
@@ -0,0 +1,61 @@
+import academicEventMapping from 'elasticsearch:./things/academic-event.js#SCAcademicEvent';
+import articleMapping from 'elasticsearch:./things/article.js#SCArticle';
+import assessmentMapping from 'elasticsearch:./things/assessment.js#SCAssessment';
+import bookMapping from 'elasticsearch:./things/book.js#SCBook';
+import buildingMapping from 'elasticsearch:./things/building.js#SCBuilding';
+import catalogMapping from 'elasticsearch:./things/catalog.js#SCCatalog';
+import certificationMapping from 'elasticsearch:./things/certification.js#SCCertification';
+import contactPointMapping from 'elasticsearch:./things/contact-point.js#SCContactPoint';
+import courseOfStudyMapping from 'elasticsearch:./things/course-of-study.js#SCCourseOfStudy';
+import dateSeriesMapping from 'elasticsearch:./things/date-series.js#SCDateSeries';
+import dishMapping from 'elasticsearch:./things/dish.js#SCDish';
+import floorMapping from 'elasticsearch:./things/floor.js#SCFloor';
+import idCardMapping from 'elasticsearch:./things/id-card.js#SCIdCard';
+import jopPostingMapping from 'elasticsearch:./things/job-posting.js#SCJobPosting';
+import messageMapping from 'elasticsearch:./things/message.js#SCMessage';
+import organizationMapping from 'elasticsearch:./things/organization.js#SCOrganization';
+import periodicalMapping from 'elasticsearch:./things/periodical.js#SCPeriodical';
+import personMapping from 'elasticsearch:./things/person.js#SCPerson';
+import pointOfInterestMapping from 'elasticsearch:./things/point-of-interest.js#SCPointOfInterest';
+import publicationEventMapping from 'elasticsearch:./things/publication-event.js#SCPublicationEvent';
+import roomMapping from 'elasticsearch:./things/room.js#SCRoom';
+import semesterMapping from 'elasticsearch:./things/semester.js#SCSemester';
+import sportCourseMapping from 'elasticsearch:./things/sport-course.js#SCSportCourse';
+import studyModuleMapping from 'elasticsearch:./things/study-module.js#SCStudyModule';
+import ticketMapping from 'elasticsearch:./things/ticket.js#SCTicket';
+import todoMapping from 'elasticsearch:./things/todo.js#SCToDo';
+import tourMapping from 'elasticsearch:./things/tour.js#SCTour';
+import videoMapping from 'elasticsearch:./things/video.js#SCVideo';
+import {SCIndexableThings} from './meta.js';
+
+export type IndexableThingTypes = SCIndexableThings['type'];
+export const elasticsearchMappings: Record<IndexableThingTypes, unknown> = {
+  'academic event': academicEventMapping,
+  'article': articleMapping,
+  'assessment': assessmentMapping,
+  'book': bookMapping,
+  'building': buildingMapping,
+  'catalog': catalogMapping,
+  'certification': certificationMapping,
+  'contact point': contactPointMapping,
+  'course of study': courseOfStudyMapping,
+  'date series': dateSeriesMapping,
+  'dish': dishMapping,
+  'floor': floorMapping,
+  'id card': idCardMapping,
+  'job posting': jopPostingMapping,
+  'message': messageMapping,
+  'organization': organizationMapping,
+  'periodical': periodicalMapping,
+  'person': personMapping,
+  'point of interest': pointOfInterestMapping,
+  'publication event': publicationEventMapping,
+  'room': roomMapping,
+  'semester': semesterMapping,
+  'sport course': sportCourseMapping,
+  'study module': studyModuleMapping,
+  'ticket': ticketMapping,
+  'todo': todoMapping,
+  'tour': tourMapping,
+  'video': videoMapping,
+};
--- a/packages/core/src/generators.d.ts
+++ b/packages/core/src/generators.d.ts
@@ -0,0 +1,10 @@
+declare module 'schema:*' {
+  import {JSONSchema7} from 'json-schema';
+  const schema: JSONSchema7;
+  export default schema;
+}
+
+declare module 'elasticsearch:*' {
+  const indexRequest: unknown;
+  export default indexRequest;
+}
--- a/packages/core/src/protocol/route.ts
+++ b/packages/core/src/protocol/route.ts
@@ -27,6 +27,7 @@ import {SCSearchRequest, SCSearchResponse, SCSearchRoute} from './routes/search.
 import {SCMultiSearchRequest, SCMultiSearchResponse, SCMultiSearchRoute} from './routes/search-multi.js';
 import {SCThingUpdateRequest, SCThingUpdateResponse, SCThingUpdateRoute} from './routes/thing-update.js';
 import {SCRatingRequest, SCRatingResponse, SCRatingRoute} from './routes/rating.js';
+import {JSONSchema7} from 'json-schema';

 /**
 * Possible Verbs for HTTP requests
@@ -50,7 +51,7 @@ export interface SCRoute {
  /**
   * A map of names of possible errors that can be returned by the route with their appropriate status codes
   */
-  errorNames: SCErrorResponseConstructor[];
+  errors: ReadonlyArray<SCErrorResponseConstructor>;

  /**
   * HTTP verb to use to request the route
@@ -65,12 +66,12 @@ export interface SCRoute {
  /**
   * Name of the type of the request body
   */
-  requestBodyName: string;
+  requestBodySchema: JSONSchema7;

  /**
   * Name of the type of the response body
   */
-  responseBodyName: string;
+  responseBodySchema: JSONSchema7;

  /**
   * Status code for success
@@ -90,7 +91,7 @@ export abstract class SCAbstractRoute implements SCRoute {
  /**
   * @see SCRoute.errorNames
   */
-  errorNames: SCErrorResponseConstructor[] = [];
+  errorSchemas: SCErrorResponseConstructor[] = [];

  /**
   * @see SCRoute.method
@@ -103,14 +104,14 @@ export abstract class SCAbstractRoute implements SCRoute {
  obligatoryParameters?: Record<string, string>;

  /**
-   * @see SCRoute.requestBodyName
+   * @see SCRoute.requestBodySchema
   */
-  requestBodyName = 'any';
+  abstract requestBodySchema: JSONSchema7;

  /**
-   * @see SCRoute.responseBodyName
+   * @see SCRoute.responseBodySchema
   */
-  responseBodyName = 'any';
+  abstract responseBodySchema: JSONSchema7;

  /**
   * @see SCRoute.statusCodeSuccess
--- a/packages/core/src/protocol/routes/bulk-add.ts
+++ b/packages/core/src/protocol/routes/bulk-add.ts
@@ -28,17 +28,23 @@ import {SCAbstractRoute, SCRouteHttpVerbs} from '../route.js';
 * @validatable
 */
 export type SCBulkAddRequest = SCThings;
+import {default as bulkAddRequestSchema} from 'schema:#SCBulkAddRequest';

 /**
 * Response to a request to add a thing to a bulk
 * @validatable
 */
 export interface SCBulkAddResponse {}
+import {default as bulkAddResponseSchema} from 'schema:#SCBulkAddResponse';

 /**
 * Route for indexing SC things in a bulk
 */
 export class SCBulkAddRoute extends SCAbstractRoute {
+  responseBodySchema = bulkAddRequestSchema;
+
+  requestBodySchema = bulkAddResponseSchema;
+
  constructor() {
    super();
    this.errorNames = [
@@ -54,8 +60,6 @@ export class SCBulkAddRoute extends SCAbstractRoute {
    this.obligatoryParameters = {
      UID: 'SCUuid',
    };
-    this.requestBodyName = 'SCBulkAddRequest';
-    this.responseBodyName = 'SCBulkAddResponse';
    this.statusCodeSuccess = StatusCodes.CREATED;
    this.urlPath = '/bulk/:UID';
  }
--- a/packages/core/src/protocol/routes/rating.ts
+++ b/packages/core/src/protocol/routes/rating.ts
@@ -18,16 +18,17 @@ import {SCMethodNotAllowedErrorResponse} from '../errors/method-not-allowed.js';
 import {SCRequestBodyTooLargeErrorResponse} from '../errors/request-body-too-large.js';
 import {SCSyntaxErrorResponse} from '../errors/syntax-error.js';
 import {SCUnsupportedMediaTypeErrorResponse} from '../errors/unsupported-media-type.js';
-import {SCAbstractRoute, SCRouteHttpVerbs} from '../route.js';
+import {SCRoute, SCRouteHttpVerbs} from '../route.js';
 import {SCThing} from '../../things/abstract/thing.js';
 import {SCUserGroupSetting} from '../../things/setting.js';
 import {SCValidationErrorResponse} from '../errors/validation.js';
+import {default as ratingRequestSchema} from 'schema:#SCRatingRequest';
+import {default as ratingResponseSchema} from 'schema:#SCRatingResponse';

 /**
 * User rating from the app
 * Plugin needs to define its own rating request to hit the target rating system.
 * That request should extend this one and contain timestamp and other needed data.
- * @validatable
 */
 export interface SCRatingRequest {
  /**
@@ -48,28 +49,26 @@ export interface SCRatingRequest {

 /**
 * A response to a rating request
- * @validatable
 */
 export interface SCRatingResponse {}

 /**
 * Route for rating submission
 */
-export class SCRatingRoute extends SCAbstractRoute {
-  constructor() {
-    super();
-    this.errorNames = [
-      SCInternalServerErrorResponse,
-      SCMethodNotAllowedErrorResponse,
-      SCRequestBodyTooLargeErrorResponse,
-      SCSyntaxErrorResponse,
-      SCUnsupportedMediaTypeErrorResponse,
-      SCValidationErrorResponse,
-    ];
-    this.method = SCRouteHttpVerbs.POST;
-    this.requestBodyName = 'SCRatingRequest';
-    this.responseBodyName = 'SCRatingResponse';
-    this.statusCodeSuccess = StatusCodes.OK;
-    this.urlPath = '/rating';
-  }
-}
+export type SCRatingRoute = typeof ratingRoute;
+
+export const ratingRoute = Object.freeze({
+  errors: [
+    SCInternalServerErrorResponse,
+    SCMethodNotAllowedErrorResponse,
+    SCRequestBodyTooLargeErrorResponse,
+    SCSyntaxErrorResponse,
+    SCUnsupportedMediaTypeErrorResponse,
+    SCValidationErrorResponse,
+  ] as const,
+  method: SCRouteHttpVerbs.POST,
+  requestBodySchema: ratingRequestSchema,
+  responseBodySchema: ratingResponseSchema,
+  statusCodeSuccess: StatusCodes.OK,
+  urlPath: '/rating',
+}) satisfies Readonly<SCRoute>;
--- a/packages/core/src/protocol/routes/search-multi.ts
+++ b/packages/core/src/protocol/routes/search-multi.ts
@@ -20,9 +20,11 @@ import {SCSyntaxErrorResponse} from '../errors/syntax-error.js';
 import {SCTooManyRequestsErrorResponse} from '../errors/too-many-requests.js';
 import {SCUnsupportedMediaTypeErrorResponse} from '../errors/unsupported-media-type.js';
 import {SCValidationErrorResponse} from '../errors/validation.js';
-import {SCAbstractRoute, SCRouteHttpVerbs} from '../route.js';
+import {SCRoute, SCRouteHttpVerbs} from '../route.js';
 import {SCSearchQuery} from '../search/query.js';
 import {SCSearchResult} from '../search/result.js';
+import {default as multiSearchRequestSchema} from 'schema:#SCMultiSearchRequest';
+import {default as multiSearchResponseSchema} from 'schema:#SCMultiSearchResponse';

 /**
 * A multi search request
@@ -30,7 +32,6 @@ import {SCSearchResult} from '../search/result.js';
 * This is a map of [[SCSearchRequest]]s indexed by name.
 *
 * **CAUTION: This is limited to an amount of queries. Currently this limit is 5.**
- * @validatable
 */
 export type SCMultiSearchRequest = Record<string, SCSearchQuery>;

@@ -38,29 +39,27 @@ export type SCMultiSearchRequest = Record<string, SCSearchQuery>;
 * A multi search response
 *
 * This is a map of [[SCSearchResponse]]s indexed by name
- * @validatable
 */
 export type SCMultiSearchResponse = Record<string, SCSearchResult>;

 /**
 * Route for submission of multiple search requests at once
 */
-export class SCMultiSearchRoute extends SCAbstractRoute {
-  constructor() {
-    super();
-    this.errorNames = [
-      SCInternalServerErrorResponse,
-      SCMethodNotAllowedErrorResponse,
-      SCRequestBodyTooLargeErrorResponse,
-      SCSyntaxErrorResponse,
-      SCTooManyRequestsErrorResponse,
-      SCUnsupportedMediaTypeErrorResponse,
-      SCValidationErrorResponse,
-    ];
-    this.method = SCRouteHttpVerbs.POST;
-    this.requestBodyName = 'SCMultiSearchRequest';
-    this.responseBodyName = 'SCMultiSearchResponse';
-    this.statusCodeSuccess = StatusCodes.OK;
-    this.urlPath = '/search/multi';
-  }
-}
+export type SCMultiSearchRoute = typeof multiSearchRoute;
+
+export const multiSearchRoute = Object.freeze({
+  errors: [
+    SCInternalServerErrorResponse,
+    SCMethodNotAllowedErrorResponse,
+    SCRequestBodyTooLargeErrorResponse,
+    SCSyntaxErrorResponse,
+    SCTooManyRequestsErrorResponse,
+    SCUnsupportedMediaTypeErrorResponse,
+    SCValidationErrorResponse,
+  ] as const,
+  method: SCRouteHttpVerbs.POST,
+  requestBodySchema: multiSearchRequestSchema,
+  responseBodySchema: multiSearchResponseSchema,
+  statusCodeSuccess: StatusCodes.OK,
+  urlPath: '/search/multi',
+}) satisfies Readonly<SCRoute>;
--- a/packages/core/src/protocol/routes/search.ts
+++ b/packages/core/src/protocol/routes/search.ts
@@ -19,40 +19,39 @@ import {SCRequestBodyTooLargeErrorResponse} from '../errors/request-body-too-lar
 import {SCSyntaxErrorResponse} from '../errors/syntax-error.js';
 import {SCUnsupportedMediaTypeErrorResponse} from '../errors/unsupported-media-type.js';
 import {SCValidationErrorResponse} from '../errors/validation.js';
-import {SCAbstractRoute, SCRouteHttpVerbs} from '../route.js';
+import {SCRoute, SCRouteHttpVerbs} from '../route.js';
 import {SCSearchQuery} from '../search/query.js';
 import {SCSearchResult} from '../search/result.js';
+import {default as searchRequestSchema} from 'schema:#SCSearchRequest';
+import {default as searchResponseSchema} from 'schema:#SCSearchResponse';

 /**
 * A search request
- * @validatable
 */
 export type SCSearchRequest = SCSearchQuery;

 /**
 * A search response
- * @validatable
 */
 export type SCSearchResponse = SCSearchResult;

 /**
 * Route for searching things
 */
-export class SCSearchRoute extends SCAbstractRoute {
-  constructor() {
-    super();
-    this.errorNames = [
-      SCInternalServerErrorResponse,
-      SCMethodNotAllowedErrorResponse,
-      SCRequestBodyTooLargeErrorResponse,
-      SCSyntaxErrorResponse,
-      SCUnsupportedMediaTypeErrorResponse,
-      SCValidationErrorResponse,
-    ];
-    this.method = SCRouteHttpVerbs.POST;
-    this.requestBodyName = 'SCSearchRequest';
-    this.responseBodyName = 'SCSearchResponse';
-    this.statusCodeSuccess = StatusCodes.OK;
-    this.urlPath = '/search';
-  }
-}
+export type SCSearchRoute = typeof searchRoute;
+
+export const searchRoute = Object.freeze({
+  errors: [
+    SCInternalServerErrorResponse,
+    SCMethodNotAllowedErrorResponse,
+    SCRequestBodyTooLargeErrorResponse,
+    SCSyntaxErrorResponse,
+    SCUnsupportedMediaTypeErrorResponse,
+    SCValidationErrorResponse,
+  ] as const,
+  method: SCRouteHttpVerbs.POST,
+  requestBodySchema: searchRequestSchema,
+  responseBodySchema: searchResponseSchema,
+  statusCodeSuccess: StatusCodes.OK,
+  urlPath: '/search',
+}) satisfies Readonly<SCRoute>;
--- a/packages/core/src/protocol/routes/thing-update.ts
+++ b/packages/core/src/protocol/routes/thing-update.ts
@@ -21,43 +21,42 @@ import {SCRequestBodyTooLargeErrorResponse} from '../errors/request-body-too-lar
 import {SCSyntaxErrorResponse} from '../errors/syntax-error.js';
 import {SCUnsupportedMediaTypeErrorResponse} from '../errors/unsupported-media-type.js';
 import {SCValidationErrorResponse} from '../errors/validation.js';
-import {SCAbstractRoute, SCRouteHttpVerbs} from '../route.js';
+import {SCRoute, SCRouteHttpVerbs} from '../route.js';
+import {default as thingUpdateRequestSchema} from 'schema:#SCThingUpdateRequest';
+import {default as thingUpdateResponseSchema} from 'schema:#SCThingUpdateResponse';

 /**
 * Request to update an existing thing
- * @validatable
 */
 export type SCThingUpdateRequest = SCThings;

 /**
 * Response for an entity update request
- * @validatable
 */
 export interface SCThingUpdateResponse {}

 /**
 * Route for updating existing things
 */
-export class SCThingUpdateRoute extends SCAbstractRoute {
-  constructor() {
-    super();
-    this.errorNames = [
-      SCInternalServerErrorResponse,
-      SCMethodNotAllowedErrorResponse,
-      SCNotFoundErrorResponse,
-      SCRequestBodyTooLargeErrorResponse,
-      SCSyntaxErrorResponse,
-      SCUnsupportedMediaTypeErrorResponse,
-      SCValidationErrorResponse,
-    ];
-    this.method = SCRouteHttpVerbs.PUT;
-    this.obligatoryParameters = {
-      TYPE: 'SCThingType',
-      UID: 'SCUuid',
-    };
-    this.requestBodyName = 'SCThingUpdateRequest';
-    this.responseBodyName = 'SCThingUpdateResponse';
-    this.statusCodeSuccess = StatusCodes.OK;
-    this.urlPath = '/:TYPE/:UID';
-  }
-}
+export type SCThingUpdateRoute = typeof thingUpdateRoute;
+
+export const thingUpdateRoute = Object.freeze({
+  errors: [
+    SCInternalServerErrorResponse,
+    SCMethodNotAllowedErrorResponse,
+    SCNotFoundErrorResponse,
+    SCRequestBodyTooLargeErrorResponse,
+    SCSyntaxErrorResponse,
+    SCUnsupportedMediaTypeErrorResponse,
+    SCValidationErrorResponse,
+  ] as const,
+  method: SCRouteHttpVerbs.PUT,
+  obligatoryParameters: {
+    TYPE: 'SCThingType',
+    UID: 'SCUuid',
+  },
+  requestBodySchema: thingUpdateRequestSchema,
+  responseBodySchema: thingUpdateResponseSchema,
+  statusCodeSuccess: StatusCodes.OK,
+  urlPath: '/:TYPE/:UID',
+}) satisfies Readonly<SCRoute>;
--- a/packages/core/src/schemas.ts
+++ b/packages/core/src/schemas.ts
@@ -0,0 +1,67 @@
+import academicEventSchema from 'schema:./things/academic-event.js#SCAcademicEvent';
+import articleSchema from 'schema:./things/article.js#SCArticle';
+import assessmentSchema from 'schema:./things/assessment.js#SCAssessment';
+import bookSchema from 'schema:./things/book.js#SCBook';
+import buildingSchema from 'schema:./things/building.js#SCBuilding';
+import catalogSchema from 'schema:./things/catalog.js#SCCatalog';
+import certificationSchema from 'schema:./things/certification.js#SCCertification';
+import contactPointSchema from 'schema:./things/contact-point.js#SCContactPoint';
+import courseOfStudySchema from 'schema:./things/course-of-study.js#SCCourseOfStudy';
+import dateSeriesSchema from 'schema:./things/date-series.js#SCDateSeries';
+import diffSchema from 'schema:./things/diff.js#SCDiff';
+import dishSchema from 'schema:./things/dish.js#SCDish';
+import favoriteSchema from 'schema:./things/favorite.js#SCFavorite';
+import floorSchema from 'schema:./things/floor.js#SCFloor';
+import idCardSchema from 'schema:./things/id-card.js#SCIdCard';
+import jopPostingSchema from 'schema:./things/job-posting.js#SCJobPosting';
+import messageSchema from 'schema:./things/message.js#SCMessage';
+import organizationSchema from 'schema:./things/organization.js#SCOrganization';
+import periodicalSchema from 'schema:./things/periodical.js#SCPeriodical';
+import personSchema from 'schema:./things/person.js#SCPerson';
+import pointOfInterestSchema from 'schema:./things/point-of-interest.js#SCPointOfInterest';
+import publicationEventSchema from 'schema:./things/publication-event.js#SCPublicationEvent';
+import roomSchema from 'schema:./things/room.js#SCRoom';
+import semesterSchema from 'schema:./things/semester.js#SCSemester';
+import settingSchema from 'schema:./things/setting.js#SCSetting';
+import sportCourseSchema from 'schema:./things/sport-course.js#SCSportCourse';
+import studyModuleSchema from 'schema:./things/study-module.js#SCStudyModule';
+import ticketSchema from 'schema:./things/ticket.js#SCTicket';
+import todoSchema from 'schema:./things/todo.js#SCToDo';
+import tourSchema from 'schema:./things/tour.js#SCTour';
+import videoSchema from 'schema:./things/video.js#SCVideo';
+import {SCThingType} from './things/abstract/thing.js';
+import {JSONSchema7} from 'json-schema';
+
+export const thingSchemas: Record<SCThingType, JSONSchema7> = {
+  'academic event': academicEventSchema,
+  'article': articleSchema,
+  'assessment': assessmentSchema,
+  'book': bookSchema,
+  'building': buildingSchema,
+  'catalog': catalogSchema,
+  'certification': certificationSchema,
+  'contact point': contactPointSchema,
+  'course of study': courseOfStudySchema,
+  'date series': dateSeriesSchema,
+  'diff': diffSchema,
+  'dish': dishSchema,
+  'favorite': favoriteSchema,
+  'floor': floorSchema,
+  'id card': idCardSchema,
+  'job posting': jopPostingSchema,
+  'message': messageSchema,
+  'organization': organizationSchema,
+  'periodical': periodicalSchema,
+  'person': personSchema,
+  'point of interest': pointOfInterestSchema,
+  'publication event': publicationEventSchema,
+  'room': roomSchema,
+  'semester': semesterSchema,
+  'setting': settingSchema,
+  'sport course': sportCourseSchema,
+  'study module': studyModuleSchema,
+  'ticket': ticketSchema,
+  'todo': todoSchema,
+  'tour': tourSchema,
+  'video': videoSchema,
+};
--- a/packages/core/src/things/academic-event.ts
+++ b/packages/core/src/things/academic-event.ts
@@ -55,7 +55,6 @@ export interface SCAcademicEventWithoutReferences

 /**
 * An academic event
- * @validatable
 * @elasticsearch indexable
 */
 export interface SCAcademicEvent
@@ -74,6 +73,9 @@ export interface SCAcademicEvent
  type: SCThingType.AcademicEvent;
 }

+// export {default as academicEventSchema} from 'schema:#SCAcademicEvent';
+// export {default as academicEventElasticsearchMapping} from 'elasticsearch:#SCAcademicEvent';
+
 /**
 * Categories of academic events
 */
--- a/packages/core/src/things/ticket.ts
+++ b/packages/core/src/things/ticket.ts
@@ -45,7 +45,6 @@ export interface SCTicketWithoutReferences extends SCThingWithoutReferences {

 /**
 * A ticket
- * @validatable
 * @elasticsearch indexable
 */
 export interface SCTicket extends SCTicketWithoutReferences, SCThingInPlace {