@api-client/core 0.17.7 → 0.18.1

package/src/modeling/Bindings.ts

@@ -75,10 +75,6 @@ export interface PropertyWebBindings {
    * The list of file mime types.
    */
   fileTypes?: string[]
-  /**
-   * The patter to use wit a string scalar
-   */
-  pattern?: string
   /**
    * Whether the attribute is hidden in the schema (not a part of it).
    */

package/src/modeling/DomainEntity.ts

@@ -786,9 +786,9 @@ export class DomainEntity extends DomainElement {
   toExample(mime: string, opts: IShapeRenderOptions = {}): string | number | boolean | null | undefined {
     const shape = this.toApiShape()
     const generator = new ApiSchemaGenerator(mime, {
-      renderExamples: typeof opts.renderExamples === 'boolean' ? opts.renderExamples : true,
-      renderMocked: typeof opts.renderMocked === 'boolean' ? opts.renderMocked : true,
-      renderOptional: typeof opts.renderOptional === 'boolean' ? opts.renderOptional : true,
+      renderExamples: opts.renderExamples ?? true,
+      renderMocked: opts.renderMocked ?? true,
+      renderOptional: opts.renderOptional ?? true,
       selectedUnions: opts.selectedUnions,
     })
     return generator.generate(shape)

package/src/modeling/DomainProperty.ts

@@ -23,6 +23,8 @@ import type { DomainEntity } from './DomainEntity.js'
 import type { IApiPropertyShape } from '../amf/definitions/Shapes.js'
 import type { PropertySchema } from './types.js'
 import { DataSemantics, isPropertySemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
+import { ApiSchemaGenerator } from '../amf/ApiSchemaGenerator.js'
+import type { IShapeRenderOptions } from '../amf/shape/ShapeBase.js'
 
 export interface DomainPropertySchema extends DomainElementSchema {
   kind: typeof DomainPropertyKind
@@ -545,6 +547,37 @@ export class DomainProperty extends DomainElement {
     return serializer.property(this)
   }
 
+  /**
+   * Generates an example value for this property based on its schema and type.
+   *
+   * This method converts the property to an AMF shape and then generates
+   * an example value using the ApiSchemaGenerator. The generated example
+   * respects the property's type, constraints, and any defined schema.
+   *
+   * @param mime The mime type of the example (e.g., 'application/json', 'application/xml').
+   * @param opts Optional configuration for example generation.
+   * @returns The generated example value.
+   * @example
+   * ```typescript
+   * const example = property.toExample('application/json');
+   * console.log(example);
+   * ```
+   */
+  toExample(mime: string, opts: IShapeRenderOptions = {}): string | number | boolean | null | undefined {
+    // TODO: add support for semantic extensions and generate example values based on them.
+    const shape = this.toApiShape()
+    if (!shape.range) {
+      return undefined
+    }
+    const generator = new ApiSchemaGenerator(mime, {
+      renderExamples: opts.renderExamples ?? true,
+      renderMocked: opts.renderMocked ?? true,
+      renderOptional: opts.renderOptional ?? true,
+      selectedUnions: opts.selectedUnions,
+    })
+    return generator.generate(shape)
+  }
+
   /**
    * Adds or updates a semantic to the property.
    * @param semantic The semantic to add to the property.

package/src/modeling/amf/ShapeGenerator.ts

@@ -464,11 +464,11 @@ export class ShapeGenerator {
     if (bindings?.xml) {
       result.xmlSerialization = bindings.xml
     }
-    if (bindings?.pattern) {
-      result.pattern = bindings.pattern
-    }
     const { schema, type } = input
     if (schema) {
+      if (schema.pattern) {
+        result.pattern = schema.pattern
+      }
       if (typeof schema.multipleOf === 'number') {
         result.multipleOf = schema.multipleOf
       }

package/src/modeling/types.ts

@@ -183,6 +183,10 @@ export interface PropertySchema {
    * They are always encoded as strings. The actual type is defined in the `dataType` property.
    */
   examples?: string[]
+  /**
+   * The pattern to use with a string scalar.
+   */
+  pattern?: string
 }
 
 /**

package/src/models/DataCatalog.ts

@@ -1,3 +1,4 @@
+import type { DataCatalogLifecycle } from './DataCatalogVersion.js'
 import { DataCatalogKind } from './kinds.js'
 
 export type DataCatalogScope = 'public' | 'private' | 'organization'
@@ -102,6 +103,17 @@ export interface DataCatalogSchema {
   tags: string[]
 }
 
+export interface DataCatalogSchemaVersion {
+  /**
+   * The version of the data catalog entry.
+   */
+  version: string
+  /**
+   * The lifecycle of the data catalog version.
+   */
+  lifecycle: DataCatalogLifecycle
+}
+
 /**
  * Used with API communication when listing data catalog entries.
  */
@@ -110,7 +122,7 @@ export interface DataCatalogSchemaWithVersion extends DataCatalogSchema {
    * The list of published versions of the data catalog entry.
    * Note, this is limited to the last 20 versions.
    */
-  versions: string[]
+  versions: DataCatalogSchemaVersion[]
 }
 
 export interface DataCatalogVersionInfo {

package/tests/unit/modeling/amf/shape_generator.spec.ts

@@ -452,14 +452,9 @@ test.group('property() / with web bindings', (group) => {
 
   test('sets the pattern', ({ assert }) => {
     const p1 = e1.addProperty({ key: 'p1', type: 'string', info: { name: 'p1' } })
-    p1.bindings = [
-      {
-        type: 'web',
-        schema: {
-          pattern: 'a-z',
-        },
-      },
-    ]
+    p1.schema = {
+      pattern: 'a-z',
+    }
     const result = p1.toApiShape()
     const string = result.range as IApiScalarShape
     assert.equal(string.pattern, 'a-z')

package/tests/unit/modeling/domain_property.spec.ts

@@ -1042,3 +1042,338 @@ test.group('DomainProperty with GeospatialCoordinates semantic', () => {
     await assert.dispatches(dataDomain, 'change', { timeout: 20 })
   })
 })
+
+test.group('DomainProperty.toExample()', () => {
+  test('generates a string example for string property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'name', type: 'string' })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    assert.isNotEmpty(result as string)
+  })
+
+  test('generates a number example for number property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'age', type: 'number' })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'number')
+  })
+
+  test('generates a boolean example for boolean property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'active', type: 'boolean' })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'boolean')
+  })
+
+  test('generates a string example for integer property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'count', type: 'number' })
+    property.getWebBinding().format = 'int32'
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'number')
+    assert.isTrue(Number.isInteger(result as number))
+  })
+
+  test('generates a string example for datetime property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'created', type: 'datetime' })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    // Should match ISO 8601 format
+    const isoDateRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+    assert.match(result as string, isoDateRegex)
+  })
+
+  test('generates a string example for date property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'birthdate', type: 'date' })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    // Should match YYYY-MM-DD format
+    const dateRegex = /^\d{4}-\d{2}-\d{2}$/
+    assert.match(result as string, dateRegex)
+  })
+
+  test('generates a string example for time property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'appointment', type: 'time' })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    // Should match time format
+    const timeRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/
+    assert.match(result as string, timeRegex)
+  })
+
+  test('respects minimum constraint for number property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'score',
+      type: 'number',
+      schema: { minimum: 10 },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'number')
+    assert.isAtLeast(result as number, 10)
+  })
+
+  test('respects maximum constraint for number property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'score',
+      type: 'number',
+      schema: { maximum: 100 },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'number')
+    assert.isAtMost(result as number, 100)
+  })
+
+  test('respects minimum and maximum constraints for number property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'score',
+      type: 'number',
+      schema: { minimum: 10, maximum: 100 },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'number')
+    assert.isAtLeast(result as number, 10)
+    assert.isAtMost(result as number, 100)
+  })
+
+  test('respects minimum length constraint for string property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'description',
+      type: 'string',
+      schema: { minimum: 20 },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    assert.isAtLeast((result as string).length, 20)
+  })
+
+  test('respects maximum length constraint for string property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'name',
+      type: 'string',
+      schema: { maximum: 10 },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    assert.isAtMost((result as string).length, 10)
+  })
+
+  test('respects enum constraint for string property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'status',
+      type: 'string',
+      schema: { enum: ['active', 'inactive', 'pending'] },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    assert.oneOf(result as string, ['active', 'inactive', 'pending'])
+  })
+
+  test('uses default value when provided', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'status',
+      type: 'string',
+      schema: { defaultValue: { type: 'literal', value: 'default-value' } },
+    })
+
+    const result = property.toExample('application/json')
+    assert.equal(result, 'default-value')
+  })
+
+  test('handles XML mime type', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'name', type: 'string' })
+
+    const result = property.toExample('application/xml')
+    assert.typeOf(result, 'string')
+    assert.isNotEmpty(result as string)
+  })
+
+  test('handles unsupported mime type', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'name', type: 'string' })
+
+    const result = property.toExample('application/octet-stream')
+    assert.isUndefined(result)
+  })
+
+  test('returns undefined when property has no range', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const property = new DomainProperty(dataDomain, 'test-parent', { key: 'test-prop' })
+
+    // Mock the toApiShape method to return a shape without range
+    const originalToApiShape = property.toApiShape
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    property.toApiShape = () => ({ range: undefined }) as any
+
+    const result = property.toExample('application/json')
+    assert.isUndefined(result)
+
+    // Restore original method
+    property.toApiShape = originalToApiShape
+  })
+
+  test('respects renderExamples option', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'name', type: 'string' })
+    property.schema = { examples: ['example1', 'example2'] }
+
+    const result = property.toExample('application/json', { renderExamples: false })
+    assert.typeOf(result, 'string')
+    assert.notInclude(['example1', 'example2'], result as string)
+  })
+
+  test('respects renderMocked option', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'name', type: 'string' })
+
+    const result = property.toExample('application/json', { renderMocked: false })
+    // No examples and no mocked value, should return a valid empty example
+    assert.typeOf(result, 'string')
+    assert.isEmpty(result as string)
+  })
+
+  test('respects renderOptional option', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'name', type: 'string', schema: { examples: ['test'] } })
+
+    const result = property.toExample('application/json', { renderOptional: false })
+    assert.isUndefined(result, 'optional properties should not render examples when renderOptional is false')
+  })
+
+  test('handles binary property type', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'data', type: 'binary' })
+
+    const result = property.toExample('application/json')
+    assert.isUndefined(result, 'currently binary properties do not have examples')
+  })
+
+  test('handles array property type', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'tags', type: 'string', multiple: true })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    assert.isNotEmpty(result as string)
+    assert.isArray(JSON.parse(result as string), 'returns an array for "multiple" properties')
+  })
+
+  test('handles property with web binding format', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({ key: 'price', type: 'number' })
+
+    const webBinding = property.getWebBinding()
+    webBinding.format = 'float'
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'number')
+  })
+
+  test('generates consistent examples for same property', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'count',
+      type: 'number',
+      schema: { minimum: 5, maximum: 10 },
+    })
+
+    const result1 = property.toExample('application/json')
+    const result2 = property.toExample('application/json')
+
+    // Both should be numbers within the range
+    assert.typeOf(result1, 'number')
+    assert.typeOf(result2, 'number')
+    assert.isAtLeast(result1 as number, 5)
+    assert.isAtMost(result1 as number, 10)
+    assert.isAtLeast(result2 as number, 5)
+    assert.isAtMost(result2 as number, 10)
+  })
+
+  test('handles property with pattern constraint', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = model.addEntity({ key: 'test-entity' })
+    const property = entity.addProperty({
+      key: 'email',
+      type: 'string',
+      schema: { pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$' },
+    })
+
+    const result = property.toExample('application/json')
+    assert.typeOf(result, 'string')
+    assert.isNotEmpty(result as string)
+    // Should match email pattern
+    const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
+    assert.match(result as string, emailRegex)
+  })
+})