[WIP] feat: json-schema and OAS for authzen 1.0

[Oltho]

Description

This is an uplift from #186 to take into account the new model/request/response part of authorization-api-1_0-05 and also defining the expected Open API Specs 3.1 (OAS) matching HTTPS JSON Binding

Having OAS defined will enable "developer" to leverage code generation tool such as openapi-generator to generate SDK/language specific code to consume system implementing the Authzen HTTPS JSON Binding.

Additional note

1. Similar to feat: JSON schema for Access Evaluation Request/Response #186 we should enforce validation/testing of the schema, we should follow guidance provided part of feat: JSON schema for Access Evaluation Request/Response #186 (comment)
2. Some model use $ref with an attempt to override required keyword (see search-subject-request.json), which is not officially documented part of json-schema-2020-12
3. Link referencing the DRAFT URL MUST be changed before merging this PR
4. $id SHOULD be replaced with a gitlab/tag URL to the same schema
5. Some of $ref might be replace with URL similar as (4)
6. OAS might need to be flatten with hard coded to be used as standalone specs instead of "ref"
7. All the code has been manually generated, please make sure to verify for typo
8. more example SHOULD be added to help with model visualization

[Oltho]

It might be difficult to review the OAS without pulling the code locally and using OAS specifics tool.

Here's an example of OAS documentation generated via cli:

• npx @redocly/cli build-docs api/oas/authzen-1.0-openapi.json
  redoc-static.html
• openapi-generator-cli generate -i api/oas/authzen-1.0-openapi.json -g html2 -o oas-html
  index.html

---

EDIT:

You can use online tool to visualize the OAS:

1. via Swagger UI
2. Go to https://editor.swagger.io/
3. Select File > Import URL
4. Paste https://raw.githubusercontent.com/Oltho/authzen/refs/heads/feat-json-schema-1.0/api/oas/authzen-1.0-openapi.json
5. click OK
6. via redocly: https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/Oltho/authzen/refs/heads/feat-json-schema-1.0/api/oas/authzen-1.0-openapi.json

We can clearly see the issue mentioned as (2), taking the example of /access/v1/search/subject where the $.subject.id is not required:

• Looking at Swagger UI it's mark as "non-required"
  

• Looking at redocly it's mark as "required"
  

[Oltho]

should json-schema carry the syntactic rules/validation ?

Looking at the access-evaluations-api-request, we have multiple scenario (but not limited to):

1. evaluations is not present -> top-level subject, resource, action MUST be present
2. evaluations is array of size 0 -> top-level subject, resource, action MUST be present
3. evaluations is array of size > 0 & each object only has subject and resource defined -> top-level action MUST be present
4. ...

While json-schema offer syntactic validation capabilities, authzen endpoint are still flexible which will make the definition of all possible json-schema complex ?

[alexolivier]

We discussed this on last weeks call with the decision being that schema should be as strict as possible.

1. evaluations is not present -> top-level subject, resource, action MUST be present
   This should be an invalid request - if this can be caught by the JSONSchema then and flag at as such then that would be ideal.

2. evaluations is array of size 0 -> top-level subject, resource, action MUST be present
   Same as above.

3. evaluations is array of size > 0 & each object only has subject and resource defined -> top-level action MUST be present
   As long as the flattened/merged sub/act/res is a valid request then it should be allowed otherwise an invalid request. We need to add a note to the spec to clarify the merged keys expectations.