Adding the OcNOS example schema

docs/user-guide/configuration/schemas.md

@@ -6,14 +6,13 @@ This process is facilitated through the Schema CustomResource, detailed [here](l
 
 The Schema CustomResource is configured using three main parameter groups:
 
-1. __Source of Schema__: Determined by `repoURL`, `kind`, and `ref` parameters.
+1. __Source of Schema__: Determined by `repoURL`, `kind`, `ref`, `dirs`, `credentials`, and `proxy` parameters.
 2. __Schema Identification__: Specified using `provider` and `version` parameters.
 3. __Schema Parsing Method__: Configured through `models`, `includes`, and `excludes` parameters.
 
 ## Source of Schema: Repository Configuration
 
-To successfully retrieve the schema, it is essential for users to provide four key parameters: `repoURL`, `kind`, `ref` and `credentials`.
-These parameters jointly establish the methodology for schema acquisition:
+To successfully retrieve the schema, three parameters are always required: `repoURL`, `kind`, and `ref`. The `credentials` parameter is required only when the repository is private. Together these parameters establish the methodology for schema acquisition:
 
 * `repoURL`: This parameter is pivotal as it specifies the repository's URL where the schema is located.
 * `kind`: It determines the nature of the reference point within the repository, offering options between a "tag" or a "branch".
@@ -101,6 +100,10 @@ The schema is uniquely identified through `provider` and `version`.
 * `provider`: Contains details about the schema issuer, typically including vendor and chassis type.
 * `version`: Represents the specific version of the schema.
 
+!!!note "One Schema CR per vendor release and platform type"
+
+    SDC uses a separate Schema CR for each combination of vendor, platform type, and release. If a vendor supports multiple platform types with different feature sets, define a separate Schema CR for each — using a distinct `provider` value (for example `ocnos-otherplatform.ipinfusion.sdcio.dev`) and adjusting `models` or `excludes` to match that platform's supported feature set.
+
 ## Schema Parsing Method: Handling YANG Models
 
 YANG schemas are comprised of several implemented models, some of which may have dependencies on other models.
@@ -120,8 +123,8 @@ If your vendor/model is not yet documented, use the workflow below.
 
 Choose a repository and pin a specific `tag` or `branch`.
 
-* Use `kind: tag` whenever possible for reproducibility.
-* Use `ref` to pin the exact release (for example: `OcNOS-SP-7.0.0`).
+* Use `kind: tag` whenever possible for reproducibility. Set `ref` to the exact release tag (for example: `OcNOS-SP-7.0.0`).
+* Use `kind: branch` only when you need to track a mutable branch — for example, during active development or when a vendor does not publish tags. Set `ref` to the branch name (for example: `main`). Be aware that branch references are not pinned: the schema will re-clone on the next reconciliation, which can introduce unexpected changes.
 
 ### 2. Locate model roots and dependencies
 
@@ -141,7 +144,7 @@ Start with a narrow scope, then expand:
 * Add `includes` for dependency folders/files.
 * Use `excludes` to skip known unwanted trees.
 
-### 4. Validate locally with `sdc-lite` (primary)
+### 4. Validate locally with `sdc-lite`
 
 Use `sdc-lite` to validate that your Schema CR definition is functional before cluster apply.
 
@@ -204,68 +207,6 @@ Typical fixes:
 * Add directories/files to `includes`.
 * Reduce `models` scope and onboard incrementally.
 
-## OcNOS SP-7.0.0 (IP Infusion)
-
-This example onboards the native `ipi-*` YANG models for OcNOS SP-7.0.0.
-
-Source repository details:
-
-* Repository: `https://github.com/IPInfusion/OcNOS`
-* Release tag: `OcNOS-SP-7.0.0`
-* Native model path: `yang-files/ipi`
-
-The OcNOS repository does not ship the IETF base types (`ietf-inet-types`, `ietf-yang-types`) that many `ipi-*` modules import.
-A second `repositories` entry pulls those from [YangModels/yang](https://github.com/YangModels/yang), following the same pattern used for Arista.
-
-```yaml
-apiVersion: inv.sdcio.dev/v1alpha1
-kind: Schema
-metadata:
-  name: ocnos-sp.ipinfusion.sdcio.dev-7.0.0
-  namespace: default
-spec:
-  provider: ocnos-sp.ipinfusion.sdcio.dev
-  version: 7.0.0
-  repositories:
-  - repoURL: https://github.com/IPInfusion/OcNOS
-    kind: branch
-    ref: OcNOS-SP-7.0.0
-    dirs:
-    - src: yang-files/ipi
-      dst: ipi
-    schema:
-      models:
-      - ipi
-  - repoURL: https://github.com/YangModels/yang
-    kind: branch
-    ref: main
-    dirs:
-    - src: standard/ietf/RFC
-      dst: ietf
-    schema:
-      includes:
-      - ietf/ietf-inet-types.yang
-      - ietf/ietf-yang-types.yang
-```
-
-To apply:
-
-```shell
-sdc-lite schema load -t ocnos-sp-7-0-0 -f config-server-repo/example/schemas/schema-ipinfusion-ocnos-sp-7.0.0.yaml
-sdc-lite target show -t ocnos-sp-7-0-0
-```
-
-Cluster apply (optional after local validation):
-
-```shell
-kubectl apply -f schema-ipinfusion-ocnos-sp-7.0.0.yaml
-kubectl get schema ocnos-sp.ipinfusion.sdcio.dev-7.0.0 -o yaml
-```
-
-!!!note "Platform-specific schemas"
-
-    SDC uses a separate Schema CR per vendor release and platform type. For a different OcNOS platform, define a new Schema with a different `provider` value (for example `ocnos-otherplatform.ipinfusion.sdcio.dev`) and adjust `models` or `excludes` to match that platform's supported feature set.
-
 ## Examples
 
 ### SR Linux v24.10.1
@@ -412,4 +353,38 @@ config-server-repo/example/schemas/schema-arista-4.31.1f.yaml
 --8<--
 config-server-repo/example/schemas/schema-arista-4.33.0f.yaml
 --8<--
-```
+```
+
+### OcNOS SP-7.0.0 (IP Infusion)
+
+This example onboards the native `ipi-*` YANG models for OcNOS SP-7.0.0.
+
+Source repository details:
+
+* Repository: `https://github.com/IPInfusion/OcNOS`
+* Release tag: `OcNOS-SP-7.0.0`
+* Native model path: `yang-files/ipi`
+
+The OcNOS repository does not ship the IETF base types (`ietf-inet-types`, `ietf-yang-types`) that many `ipi-*` modules import.
+A second `repositories` entry pulls those from [YangModels/yang](https://github.com/YangModels/yang), following the same pattern used for Arista.
+
+```yaml
+--8<--
+config-server-repo/example/schemas/schema-ipinfusion-ocnos-sp-7.0.0.yaml
+--8<--
+```
+
+To apply:
+
+```shell
+sdc-lite schema load -t ocnos-sp-7-0-0 -f config-server-repo/example/schemas/schema-ipinfusion-ocnos-sp-7.0.0.yaml
+sdc-lite target show -t ocnos-sp-7-0-0
+```
+
+Cluster apply (optional after local validation):
+
+```shell
+kubectl apply -f schema-ipinfusion-ocnos-sp-7.0.0.yaml
+kubectl get schema ocnos-sp.ipinfusion.sdcio.dev-7.0.0 -o yaml
+```
+