Application Manifest JSON Schema

[fitmanyak]

Please provide JSON Schema (https://json-schema.org/) for Application Manifest YAML files to have ability to validate them.

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/160788311

The labels on this github issue will be updated when the story is started.

[ParkerM]

I've been working on a draft 07 schema a bit here, and have definitions/types for (I think) all of the current attributes including titles and descriptions for IDE hints. It includes validation for attributes that have documented mutual exclusions such as routes, docker, health-check-http-endpoint (for incompatible health-check-type), and uses some non-standard deprecation attributes to mark features as such.
Most of the constraints and descriptions are based on the cf app manifests docs and STS4 manifest-yaml-language-server.

Current consumable versions are deployed at https://parkerm.gitlab.io/cf-manifest-schema/json/manifest.schema.json.
If there's interest in using this work I could submit a PR, but would need some guidance as to where the schema would go or how it should be integrated.

[abbyachau]

Hi @fitmanyak @ParkerM thanks for reaching out. I've marked this an enhancement and will try to circle around again when we can.

[shalako]

As manifest parsing will be the responsibility of Cloud Controller (server-side), it seems to me the CAPI team should publish the JSON schema for the manifest. @ssisil @tcdowney

[tcdowney]

Thanks for pointing this out to us, @shalako.

@ssisil I think providing a JSON schema along with our docs here would definitely help clients consume the endpoint and we could test against it internally to guard against regressions as we make changes. Especially changes like #158669166 which will allow for multiple datatypes for the same attribute (hopefully JSON schema can handle this case 🤞). We already make use of JSON schema for our services endpoints to ensure compatibility with the Open Service Broker API (see these tests) so it's definitely not unprecedented.

Also big thanks to @ParkerM for the work on that draft schema, really helps to visualize what this could look like for the manifests. 💯

[ParkerM]

Especially changes like #158669166 which will allow for multiple datatypes for the same attribute (hopefully JSON schema can handle this case 🤞).

If I understand this part correctly, then JSON schema (at least draft 07) should be more than capable of handling such cases through the built-in logical operators. Basic example here.

E.g. if a service has parameter foo, we could constrain that specific param to either be a boolean, a non-negative number, or some other more complex type with the following:

"services": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "parameters": {
        "type": "object",
        "foo": {
          "oneOf": [
            {"type": "boolean"},
            {"type": "number", "minimum": 0},
            {"$ref": "#/definitions/superfoo"}
          ]
        }
      }
    }
  }
}

The $ref keyword is notably powerful for DRY/extensibility, and can also reference remote schemas. It may even be possible for service offerings to provide their own discoverable "live" schemas against which a generic manifest schema could be used to validate a manifest's services config, potentially preventing a botched deploy.

[gberche-orange]

@tcdowney

I think providing a JSON schema along with our docs [here](http://v3-apidocs.cloudfoundry.org/version/3.68.0/index.html#app-manifest) would definitely help clients consume the endpoint

The Json schema are likely to be used by developers in their preferred IDE (e.g. in intellij), which automatically selects and downloads the associated Json schema based on registered file patterns (in our case ./manifest.yml) in http://schemastore.org/json/, and then provides completion as well as inline documentation/hints.

That'd be awesome in the future to have concourse pipeline submitting upstream PRs when new versions of the application manifest schema gets published, and leave it up to ides/app developers to select the appropriate version matching their CF deployment (see related https://github.com/SchemaStore/schemastore/issues/197#issuecomment-229690162)

CF web uis, may also need to download and use the Cf Json schema corresponding to the version of currently targetted api endpoint, and automatically generate user-facing forms to edit the application. It might be useful to have the json schema being downloadeable from an easily discoverable endpoint (e.g. json schema url be listed in /v2/info endpoint). Currently, the /v2/info endpoint returns an api_version such as "api_version": "2.123.0" whereas the apidocs endpoint seems to expect a capi version as path parameter such as https://apidocs.cloudfoundry.org/4.5.0/

[abbyachau]

Hi folks, I'm going to transfer this issue to CAPI since sever side manifest is handled by them in V3.

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/165573199

The labels on this github issue will be updated when the story is started.