refactor(pkg/go)!: restructure validation and errors

docs/validation/model/README.md

@@ -21,7 +21,7 @@ OpenFGA model validation ensures that authorization models are syntactically cor
 |------------|------------|---------|---------------|
 | `schema-version-required` | Schema | Schema version must be specified | [schema-version-required.md](./schema-version-required.md) |
 | `schema-version-unsupported` | Schema | Unsupported schema version | [schema-version-unsupported.md](./schema-version-unsupported.md) |
-| `invalid-schema-version` | Schema | Invalid schema version format | [invalid-schema-version.md](./invalid-schema-version.md) |
+| `invalid-schema-version` | Schema | Declared but not emitted; an unrecognised version reports `invalid-schema` | [invalid-schema-version.md](./invalid-schema-version.md) |
 | `reserved-type-keywords` | Naming | Type name uses reserved keyword | [reserved-type-keywords.md](./reserved-type-keywords.md) |
 | `reserved-relation-keywords` | Naming | Relation name uses reserved keyword | [reserved-relation-keywords.md](./reserved-relation-keywords.md) |
 | `self-error` | Naming | Invalid use of 'self' or 'this' | [self-error.md](./self-error.md) |
@@ -44,9 +44,15 @@ OpenFGA model validation ensures that authorization models are syntactically cor
 | `condition-not-used` | Condition | Defined condition is never used | [condition-not-used.md](./condition-not-used.md) |
 | `different-nested-condition-name` | Condition | Condition name mismatch in nested structure | [different-nested-condition-name.md](./different-nested-condition-name.md) |
 | `multiple-modules-in-file` | Multi-file | Multiple modules detected in single file | [multiple-modules-in-file.md](./multiple-modules-in-file.md) |
-| `invalid-schema` | Schema | Invalid schema structure | [invalid-schema.md](./invalid-schema.md) |
+| `invalid-schema` | Schema | Unrecognised schema version | [invalid-schema.md](./invalid-schema.md) |
 | `invalid-syntax` | Syntax | Invalid DSL syntax | [invalid-syntax.md](./invalid-syntax.md) |
 
+Five of the codes above are declared but never emitted, so no validation output
+carries them: `invalid-schema-version`, `self-error`, `invalid-syntax`, `cyclic-error`
+and `cyclic-relation`. An unrecognised schema version reports `invalid-schema`, and a
+cycle with no entrypoint reports `relation-no-entry-point`. Their pages are kept
+because each is a published URL.
+
 ## Usage
 
 Each error documentation includes:

docs/validation/model/TROUBLESHOOTING_GUIDE.md

@@ -19,9 +19,9 @@ This guide provides quick solutions to common OpenFGA validation errors. For det
 | Error | Quick Fix                                    | Link |
 |-------|----------------------------------------------|------|
 | `invalid-syntax` | Check indentation and keyword spelling       | [Details](./invalid-syntax.md) |
-| `invalid-schema` | Ensure proper `model` and `schema` structure | [Details](./invalid-schema.md) |
+| `invalid-schema` | Declare a recognised version (`1.1` or `1.2`) | [Details](./invalid-schema.md) |
 | `schema-version-unsupported` | Use supported version (`1.1` or `1.2`)           | [Details](./schema-version-unsupported.md) |
-| `invalid-schema-version` | Use format `X.Y` (e.g., `1.1`)               | [Details](./invalid-schema-version.md) |
+| `invalid-schema-version` | Not emitted; an unrecognised version arrives as `invalid-schema` above | [Details](./invalid-schema-version.md) |
 
 ### Relationship and Reference Errors
 

docs/validation/model/invalid-schema-version.md

@@ -6,131 +6,22 @@
 
 ## Summary
 
-The schema version format is invalid or malformed, preventing proper model validation and execution.
+An unrecognised schema version is reported under [`invalid-schema`](./invalid-schema.md).
 
 ## Description
 
-OpenFGA schema versions must follow a specific format to ensure proper parsing and feature detection. Valid schema versions:
-- Follow semantic versioning format (e.g., "1.1", "1.2")
-- Use numeric values separated by dots
-- Contain only supported version numbers
-- Cannot be empty or contain invalid characters
+`1.1` and `1.2` are the versions OpenFGA accepts. A version outside that set is reported as `invalid-schema`, with the version as the symbol, so `schema 0.9` gives the message `invalid schema 0.9`.
 
-Invalid schema version formats prevent the validation system from determining which features are available and which validation rules to apply.
+Two neighbouring conditions have codes of their own. Version `1.0` is recognised and retired, so it reports [`schema-version-unsupported`](./schema-version-unsupported.md), and a model carrying no version at all reports [`schema-version-required`](./schema-version-required.md).
 
-## Example
-
-The following models would trigger this error:
-
-### Invalid version formats:
-```
-model
-  schema v1.1        # Error: contains 'v' prefix
-
-model
-  schema 1.1.0.0     # Error: too many version parts
-
-model
-  schema 1.x         # Error: non-numeric version part
-
-model
-  schema ""          # Error: empty version string
-
-model
-  schema 1.1-beta    # Error: contains suffix
-```
-
-**Error Message:** `Invalid schema version format: 'v1.1'. Schema version must be in format 'X.Y'`
+A `schema` line that does not parse as a version at all, such as `schema v1.1`, `schema 1.1.0`, or `schema` on its own, fails during DSL transformation and returns a syntax error with no error code attached.
 
 ## Resolution
 
-Use proper schema version format:
-
-### Correct schema version formats:
-```
-model
-  schema 1.1    # Valid: current recommended version
-
-model
-  schema 1.2    # Valid: current recommended version + module support
-```
-
-### Steps to fix:
-
-1. **Identify the format issue:**
-   - Check the error message for the specific format problem
-   - Review the schema version declaration in your model
-
-2. **Use correct format:**
-   - Remove any prefixes (v, version, etc.)
-   - Use only numeric values separated by a single dot
-   - Remove any suffixes or additional version parts
-
-3. **Choose appropriate version:**
-   - Use `1.1` or `1.2` for new models (recommended)
-   - Use `1.2` when using modules
-
-4. **Update and validate:**
-   - Correct the schema version format
-   - Ensure your model features are compatible with the chosen version
-
-## Valid Schema Version Examples
-
-### ✅ Correct formats:
-```
-model
-  schema 1.1
-
-model
-  schema 1.2
-```
-
-### ❌ Invalid formats:
-```
-model
-  schema v1.1          # Prefix not allowed
-
-model
-  schema 1.1.0         # Too many parts
-
-model
-  schema 1.x           # Non-numeric
-
-model
-  schema 1.1-beta      # Suffix not allowed
-
-model
-  schema version 1.1   # Extra text
-```
-
-## Feature Compatibility Matrix
-
-| Feature                              | Schema 1.0 | Schema 1.1 | Schema 1.2 |
-|--------------------------------------|------------|------------|------------|
-| Supported                            | ❌          | ✅          | ✅          |
-| Basic relations                      | ✅          | ✅          | ✅          |
-| Simple wildcards                     | ✅          | ✅          | ✅          |
-| Wildcards                            | ✅          | ✅          | ✅          |
-| Basic operations                     | ✅          | ✅          | ✅          |
-| Type Restrictions                    | ❌          | ✅          | ✅          |
-| Conditions                           | ❌          | ✅          | ✅          |
-| Operator grouping `(a or (b and c))` | ❌          | ✅          | ✅          |
-| Modules                              | ❌          | ❌          | ✅          |
-
-> [!WARNING]
-> Schema version `1.0` is no longer supported by OpenFGA. Models using this version must be updated to `1.1` or `1.2`. See the [Schema 1.1 Migration Guide](../migrations/schema1.0-to-schema1.1.md) for assistance.
+Declare `1.1`, or `1.2` for a model split across files with `module` declarations. See [`invalid-schema`](./invalid-schema.md) for the full example and the compatibility matrix in [`schema-version-unsupported`](./schema-version-unsupported.md) for what each version supports.
 
 ## Related Errors
 
-- [`schema-version-required`](./schema-version-required.md) - When no schema version is specified
-- [`schema-version-unsupported`](./schema-version-unsupported.md) - When version is not supported
-- [`invalid-schema`](./invalid-schema.md) - General schema structure issues
-
-## Implementation Notes
-
-This validation is enforced consistently across:
-- Go implementation: `pkg/go/validation/schema_validation.go`
-- JavaScript implementation: `pkg/js/validator/validate-dsl.ts`
-- Java implementation: Java schema validation package
-
-The validation uses regular expressions to check version format and ensures consistency across all language implementations.
+- [`invalid-schema`](./invalid-schema.md) - An unrecognised schema version
+- [`schema-version-required`](./schema-version-required.md) - No schema version is declared
+- [`schema-version-unsupported`](./schema-version-unsupported.md) - Version `1.0`, recognised but retired

docs/validation/model/invalid-schema.md

@@ -6,149 +6,68 @@
 
 ## Summary
 
-The overall schema structure is invalid or malformed, preventing proper model parsing and validation.
+The model declares a schema version the validator does not recognise.
 
 ## Description
 
-This error occurs when the authorization model's schema structure doesn't conform to OpenFGA's schema requirements. Unlike specific schema version errors, this represents fundamental structural problems with the schema that prevent basic parsing and validation.
+`1.1` and `1.2` are the supported versions. A version that parses but is neither of those is reported as `invalid-schema`, with the version itself as the symbol.
 
-Common schema structure issues include:
-- Missing required schema components
-- Malformed schema declarations
-- Invalid schema syntax or formatting
-- Structural inconsistencies that violate OpenFGA's schema rules
+Two neighbouring conditions have codes of their own. Version `1.0` is recognised and retired, so it reports [`schema-version-unsupported`](./schema-version-unsupported.md), and a model carrying no version at all reports [`schema-version-required`](./schema-version-required.md).
 
-## Example
-
-The following models would trigger this error:
-
-### Missing model declaration:
-```
-schema 1.1  # Error: Missing 'model' declaration
+A malformed `schema` line never reaches validation. `schema v1.1`, `schema 1.1.0`, `schema` with no version, and a file with no `model` declaration all fail during DSL transformation with a syntax error and no error code attached.
 
-type user
+## Example
 
-type document
-  relations
-    define viewer: [user]
-```
+### DSL
 
-### Malformed schema structure:
 ```
 model
-  # Error: Schema declaration without version
-  schema
+  schema 0.9
 
 type user
 ```
 
-### Invalid schema syntax:
-```
-model {  # Error: Invalid syntax for model declaration
-  schema: 1.1
-}
+**Error Message:** `invalid schema 0.9`
 
-type user
-```
+The position covers the version itself: line 1, columns 9 to 12.
 
-**Error Message:** `Invalid schema structure: missing required model declaration`
+### JSON
 
-## Resolution
-
-Fix the schema structure to conform to OpenFGA's requirements:
-
-### Option 1: Add missing model declaration
-
-```
-model
-  schema 1.1
-
-type user
-
-type document
-  relations
-    define viewer: [user]
-```
-
-### Option 2: Fix schema syntax
-
-```
-model
-  schema 1.1  # Proper format: schema followed by version
-
-type user
-
-type document
-  relations
-    define viewer: [user]
+```json
+{
+  "schema_version": "1.3"
+}
 ```
 
-### Steps to fix:
-
-1. **Identify the structural issue:**
-   - Check the error message for specific schema structure problems
-   - Review the beginning of your model file for proper format
+**Error Message:** `invalid schema 1.3`
 
-2. **Follow OpenFGA schema format:**
-   - Start with `model` declaration
-   - Follow with `schema X.Y` version specification
-   - Use proper indentation and syntax
-
-3. **Validate basic structure:**
-   - Ensure model declaration comes first
-   - Verify schema version is properly specified
-   - Check that type definitions follow schema declaration
-
-4. **Test the corrected structure:**
-   - Validate the model after fixing schema structure
-   - Ensure the model parses correctly
+## Resolution
 
-## Valid Schema Structure
+Declare a supported version:
 
-### ✅ Correct schema format:
 ```
 model
   schema 1.1
 
 type user
-  relations
-    define profile_owner: [user]
 
 type document
   relations
     define viewer: [user]
-    define editor: [user] or viewer
 ```
 
-### ❌ Invalid schema formats:
-```
-# Missing model declaration
-schema 1.1
-type user
-
-# Wrong syntax
-model {
-  schema: 1.1
-}
-type user
-
-# Missing schema version  
-model
-  schema
-type user
-```
+Use `1.2` if the model is split across files with `module` declarations, `1.1` otherwise.
 
 ## Related Errors
 
-- [`schema-version-required`](./schema-version-required.md) - When schema version is missing
-- [`invalid-schema-version`](./invalid-schema-version.md) - When version format is invalid
-- [`invalid-syntax`](./invalid-syntax.md) - General syntax issues
+- [`schema-version-required`](./schema-version-required.md) - No schema version is declared
+- [`schema-version-unsupported`](./schema-version-unsupported.md) - Version `1.0`, recognised but retired
+- [`invalid-syntax`](./invalid-syntax.md) - Syntax problems, including a malformed `schema` line
 
 ## Implementation Notes
 
-This validation is enforced consistently across:
-- Go implementation: `pkg/go/validation/schema_validation.go`
-- JavaScript implementation: `pkg/js/validator/validate-dsl.ts`
-- Java implementation: Java schema validation package
+- Go: `ValidateSchemaVersion` in `pkg/go/validation/schema_validation.go`
+- JavaScript: `validate-dsl.ts`, through `createInvalidSchemaVersionError` in `util/exceptions.ts`
+- Java: `ModelValidator`, through `ValidationErrorsBuilder.raiseInvalidSchemaVersion`
 
-The validation performs structural checks during the initial parsing phase to ensure the model follows OpenFGA's basic schema requirements.
+All three tag the finding `invalid-schema`. The message and the code are pinned in `tests/data/dsl-semantic-validation-cases.yaml` and `tests/data/json-validation-cases.yaml`.

docs/validation/model/invalid-syntax.md

@@ -147,7 +147,7 @@ define viewer [user]  # Wrong: missing colon
 
 ## Related Errors
 
-- [`invalid-schema`](./invalid-schema.md) - When schema structure is invalid
+- [`invalid-schema`](./invalid-schema.md) - When the declared version is not recognised
 - [`invalid-name`](./invalid-name.md) - When names don't follow format rules
 - [`schema-version-required`](./schema-version-required.md) - When schema declaration is missing
 

docs/validation/model/schema-version-required.md

@@ -62,7 +62,7 @@ type document
 ## Related Errors
 
 - [`schema-version-unsupported`](./schema-version-unsupported.md) - When an unsupported version is specified
-- [`invalid-schema-version`](./invalid-schema-version.md) - When the version format is invalid
+- [`invalid-schema-version`](./invalid-schema-version.md) - Declared but not emitted; an unrecognised version reports `invalid-schema`
 
 ## Implementation Notes
 

docs/validation/model/schema-version-unsupported.md

@@ -352,8 +352,8 @@ In these cases, OpenFGA will not consider those invalid tuples when evaluating q
 ## Related Errors
 
 - [`schema-version-required`](./schema-version-required.md) - When no schema version is specified
-- [`invalid-schema-version`](./invalid-schema-version.md) - When version format is invalid
-- [`invalid-schema`](./invalid-schema.md) - General schema structure issues
+- [`invalid-schema-version`](./invalid-schema-version.md) - Schema versions and how they are reported
+- [`invalid-schema`](./invalid-schema.md) - When the declared version is not recognised
 
 ## Implementation Notes