feat: Custom param type

[daogrady]

Fixes issues/issues/21005

[daogrady]

Converting to draft, as this is a feature that is not covered in the odata standard:

"CustomParameter": {
            "$Kind": "ComplexType",
            "@Core.Description": "A custom parameter is either a header or a query option",
            "@Core.LongDescription": "The type of a custom parameter is always a string. Restrictions on the parameter values can be expressed by annotating the record expression describing the parameter with terms from the Validation vocabulary, e.g. Validation.Pattern or Validation.AllowedValues.",
            "Name": {
                "@Core.Description": "Name of the custom parameter"
            },
            "Description": {
                "$Nullable": true,
                "@Core.Description": "Description of the custom parameter"
            },
            "DocumentationURL": {
                "$Nullable": true,
                "@Core.IsURL": true,
                "@Core.Description": "URL of related documentation"
            },
            "Required": {
                "$Type": "Edm.Boolean",
                "$DefaultValue": false,
                "@Core.Description": "true: parameter is required, false or not specified: parameter is optional"
            },
            "ExampleValues": {
                "$Collection": true,
                "$Type": "Core.PrimitiveExampleValue",
                "@Core.Description": "Example values for the custom parameter"
            }
        },

https://raw.githubusercontent.com/oasis-tcs/odata-vocabularies/main/vocabularies/Org.OData.Capabilities.V1.json

explicitly states that (a) the type is always string and (b) value restrictions can be passed as such. That would mean booleans would be restricted by setting the allowed values to ["true", "false"], which is awkward. So the request to be able to pass a custom type with a matching default value makes sense.

The import already supports this, see:

// foo.cds
service DemoService {
    entity Things {
        key id   : Integer;
            name : String;
    }
}

annotate DemoService.Things with @Capabilities.InsertRestrictions.CustomHeaders: [{
    Name                : 'x-auto-activate',
    Description         : 'Auto-activate the record. Boolean, defaults to true.',
    Required            : false,
    ![@openapi.type]    : 'boolean',
    ![@openapi.default] : true
}];

then (with feat/custom-param-type checked out):

cds compile foo.cds -2 openapi > out.json

inspect the output file to find the custom type. Then

cds import --from openapi out.json

inspect the srv/external/out.csn to find the custom type again.

Still, other tools could trip over this non-standard annotation, so I am hesitant to merge it just yet.

[daogrady]

Checked with openapiviewer.com, and at least there it does not break anything:

before:

after:

[tim-sh]

Reminder (cosmetic): mind blank lines b/w headings before release

[tim-sh]

Looks good to me