Fix JSON schema: fix allow-credentials default, add missing descriptions, and relax required field constraints (#3236)

## Why make this change?

Several bugs exist in `schemas/dab.draft.schema.json` relative to the
official DAB documentation and correct JSON schema behavior:

- `runtime.host.cors.allow-credentials` had its schema `default`
incorrectly set to the string `"false"` instead of the boolean `false`,
while all other `boolean-or-string` properties in the schema used proper
boolean defaults.
- Multiple properties were missing `description` fields, reducing
IntelliSense and tooling discoverability.
- Several boolean properties did not reference
`#/$defs/boolean-or-string`, preventing users from supplying
`@env()`/`@akv()` environment variable references.
- Some `required` constraints were either missing or overly strict
relative to the documentation (e.g. `runtime.rest.enabled`,
`runtime.graphql.enabled` marked required when they are optional, and
entity fields not conditionally required).

## What is this change?

- Fixed `runtime.host.cors.allow-credentials` default from `"false"`
(JSON string) to `false` (JSON boolean), consistent with every other
`boolean-or-string` property in the schema.
- Added/expanded `description` fields across runtime and entity
configuration blocks (including `graphql.type.singular`,
`graphql.type.plural`, `relationships..cardinality`, and others) to
improve discoverability and tooling support.
- Switched multiple boolean schema properties to reference
`#/$defs/boolean-or-string`, supporting `@env('...')` / `@akv('...')`
patterns.
- Relaxed and corrected `required` constraints to better match the
documented behavior (e.g. making `runtime.rest.enabled` and
`runtime.graphql.enabled` optional, adding conditional requirements for
entity `key-fields` when source type is `view`).

## How was this tested?

- [ ] Integration Tests
- [ ] Unit Tests

## Sample Request(s)

A DAB config with CORS enabled — schema tooling (IntelliSense,
validation) will now correctly default `allow-credentials` to the
boolean `false` instead of the string `"false"`:

```jsonc
{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["https://contoso.com"],
        "allow-credentials": false
      }
    }
  }
}
```

Using an environment variable reference (enabled by the
`boolean-or-string` type):

```jsonc
{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["https://contoso.com"],
        "allow-credentials": "@env('CORS_ALLOW_CREDENTIALS')"
      }
    }
  }
}
```

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

Resolve five JSON schema bugs in Azure/data-api-builder by updating the
configuration JSON schema so it matches official docs and issue
recommendations.

Issues to resolve:

1) #2520 JSON schema: Missing descriptions
- Add descriptions:
- entities.<entity>.graphql.type.singular: "Defines the singular GraphQL
type name for the entity."
- entities.<entity>.graphql.type.plural: "Defines the plural GraphQL
type name for the entity."
- entities.<entity>.relationships.<relationship>.cardinality: "Defines
the cardinality of the relationship between entities."

2) #2519 JSON Schema: Inaccurate Required/Not-Required constraints
- Ensure data-source.options.database and data-source.options.schema are
required when data-source.database-type is cosmosdb_nosql.
- Ensure entities.<entity>.source.key-fields is required only when
entities.<entity>.source.type is "view" (and when source is the object
form, not string form).
- Ensure entities.<entity>.permissions is required for entity
definitions (consistent with docs) without breaking
stored-procedure/execute-only permission shape.
- Ensure runtime.rest.enabled and runtime.graphql.enabled are optional
and default to true.

3) #2518 JSON Schema: Missing Default Values
- Ensure runtime.graphql.allow-introspection has default true.

4) #2517 JSON Schema: Redundant "required" Properties
- Make jwt.audience and jwt.issuer conditionally required only when
authentication provider is EntraID/AzureAD (per issue: AzureAd provider)
and not required (nor causing validation errors) for providers that
don’t need them.
- Preserve current behavior that jwt object itself is required only for
providers that need JWT, and forbidden otherwise.

5) #2516 JSON Schema: Application Insights Connection String is Required
- Modify telemetry.application-insights so connection-string is required
only when enabled is true. Configuration with enabled=false and no
connection-string should validate.

Implementation notes:
- Primary schema file observed: schemas/dab.draft.schema.json. Update
the appropriate schema(s) used for validation/shipping.
- Add/adjust JSON Schema conditional blocks (if/then/else, allOf) as
needed.
- Update/add tests if the repo has schema validation tests; otherwise
add minimal tests to validate the new constraints.
- Keep formatting consistent (2-space JSON indent, LF).

Deliverables:
- Code changes implementing all fixes.
- Tests updated/added to cover the scenarios from issues.
- Open a pull request against base branch main referencing the above
issues.

The following is the prior conversation context from the user's chat
exploration (may be truncated):

User: @Azure/data-api-builder/issues/2520
@Azure/data-api-builder/issues/2519
@Azure/data-api-builder/issues/2518
@Azure/data-api-builder/issues/2517
@Azure/data-api-builder/issues/2516
Review these five bugs and report back if they are or are not resolved
in the code base

Assistant: I reviewed the **current `schemas/dab.draft.schema.json`** in
**Azure/data-api-builder** at commit
**`3199765c331340073f77b0c07666f1b1ff97b60c`** and compared it to the 5
issues.

Note: I only found/checked **`schemas/dab.draft.schema.json`** via code
search (results can be incomplete). You can browse more schema files
here:
`repo:Azure/data-api-builder path:schemas` (GitHub code search UI).

## Status per issue (resolved in codebase vs not)

### #2520 — JSON schema: Missing descriptions
**Not resolved.** (Issue is also still **open**.)
* `entities.<entity>.graphql.type` is `$ref`’d to
`#/$defs/singular-plural`.
* In `$defs.singular-plural`, **`singular`** and **`plural`** have **no
`description`** fields. (So the requested descriptions aren’t present.)
* `entities.<entity>.relationships.<relationship>.cardinality` exists
but has **no `description`**.

Evidence (file locations):
- `relationships.*.cardinality` has enum but no description:
`schemas/dab.draft.schema.json` lines ~1132-1135. citeturn2commentary
- `$defs.singular-plural` defines `singular`/`plural` without
descriptions: lines ~1448-1466. citeturn2commentary

---

### #2519 — JSON Schema: Inaccurate Required/Not-Required constraints
**Partially resolved, mostly not resolved.** (Issue is still **open**.)

**Resolved pieces:**
* `data-source.options.database` and `data-source.options.schema` are
conditionally required when `database-type` is `cosmosdb_nosql`.
* Schema has an `allOf` block that sets `options.required:
["database","schema"]` and also requires `"options"` for
`cosmosdb_nosql`.

Evidence: `data-source` `allOf` / `cosmosdb_nosql` branch requires
`database` and `schema`: lines 88-121. citeturn2commentary

**Not resolved / still discrepant:**
* `runtime.rest.enabled` and `runtime.graphql.enabled` are **not marked
required** (good), but they also **do not have `default: true`** in the
schema.
* They are `$ref`’d to `#/$defs/boolean-or-string` and no default is
specified there either.
* `entities.<entity>.permissions` **is required** — but only under ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/Azure/data-api-builder/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>
Co-authored-by: Aniruddh Munde <anmunde@microsoft.com>
Co-authored-by: Anusha Kolan <anushakolan10@gmail.com>
Co-authored-by: Souvik Ghosh <souvikofficial04@gmail.com>

Author: 5 people