feat(pkg/go): semantic validation using proto generated structs

docs/validation/model/README.md

@@ -0,0 +1,82 @@
+# OpenFGA Model Validation Errors
+
+This directory contains comprehensive documentation for all OpenFGA model validation errors. These error codes and messages are consistent across Go, JavaScript, and Java implementations to provide a unified validation experience.
+
+## Overview
+
+OpenFGA model validation ensures that authorization models are syntactically correct, semantically valid, and follow best practices. When validation fails, specific error codes and messages help identify and resolve issues.
+
+## Error Categories
+
+- **Schema Validation**: Issues with model schema versions and structure
+- **Name Validation**: Problems with type and relation naming
+- **Semantic Validation**: Logical issues like undefined references and cycles
+- **Structural Validation**: Problems with model structure and relationships
+- **Condition Validation**: Issues with condition definitions and usage
+- **Multi-file Validation**: Problems with module consistency across files
+
+## Complete Error Reference
+
+| Error Code | Error Type | Summary | Documentation |
+|------------|------------|---------|---------------|
+| `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) |
+| `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) |
+| `invalid-name` | Naming | Invalid type or relation name format | [invalid-name.md](./invalid-name.md) |
+| `duplicated-error` | Structure | Duplicate type or relation definition | [duplicated-error.md](./duplicated-error.md) |
+| `missing-definition` | Semantic | Referenced type or relation not defined | [missing-definition.md](./missing-definition.md) |
+| `undefined-type` | Semantic | Type is referenced but not defined | [undefined-type.md](./undefined-type.md) |
+| `undefined-relation` | Semantic | Relation is referenced but not defined | [undefined-relation.md](./undefined-relation.md) |
+| `invalid-relation-type` | Semantic | Invalid relation type in reference | [invalid-relation-type.md](./invalid-relation-type.md) |
+| `invalid-type` | Semantic | Invalid type in relation definition | [invalid-type.md](./invalid-type.md) |
+| `relation-no-entry-point` | Semantic | Relation has no entry point for assignment | [relation-no-entry-point.md](./relation-no-entry-point.md) |
+| `cyclic-error` | Semantic | Circular dependency in relations | [cyclic-error.md](./cyclic-error.md) |
+| `cyclic-relation` | Semantic | Circular relation dependency detected | [cyclic-relation.md](./cyclic-relation.md) |
+| `invalid-relation-on-tupleset` | Structure | Invalid relation in tuple-to-userset | [invalid-relation-on-tupleset.md](./invalid-relation-on-tupleset.md) |
+| `tupleuserset-not-direct` | Structure | Tuple-to-userset must have direct assignment | [tupleuserset-not-direct.md](./tupleuserset-not-direct.md) |
+| `invalid-wildcard-error` | Wildcard | Invalid wildcard usage in relation | [invalid-wildcard-error.md](./invalid-wildcard-error.md) |
+| `assignable-relation-must-have-type` | Wildcard | Assignable relation must specify type | [assignable-relation-must-have-type.md](./assignable-relation-must-have-type.md) |
+| `type-wildcard-relation` | Wildcard | Type restriction cannot have wildcard and relation | [type-wildcard-relation.md](./type-wildcard-relation.md) |
+| `condition-not-defined` | Condition | Referenced condition is not defined | [condition-not-defined.md](./condition-not-defined.md) |
+| `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-syntax` | Syntax | Invalid DSL syntax | [invalid-syntax.md](./invalid-syntax.md) |
+
+## Usage
+
+Each error documentation includes:
+
+- **Error Code**: The unique identifier for the error
+- **Summary**: Brief description of what causes the error
+- **Description**: Detailed explanation of the validation rule
+- **Example**: Code example that would trigger this error
+- **Resolution**: How to fix the error (step-by-step guidance)
+
+## Implementation Notes
+
+These validation errors are implemented consistently across:
+
+- **Go**: `pkg/go/validation/` package
+- **JavaScript**: `pkg/js/validator/` package  
+- **Java**: Java validation implementation
+
+Error codes, messages, and validation logic are synchronized to ensure identical behavior across all language implementations.
+
+## Contributing
+
+When adding new validation rules:
+
+1. Add the error code to all implementations (Go, JS, Java)
+2. Create documentation following the template format
+3. Add the error to this index table
+4. Include test cases in the appropriate test suites
+5. Update the YAML test files for cross-language validation
+
+## Support
+
+For questions about validation errors or to report inconsistencies between language implementations, please file an issue in the [OpenFGA Language repository](https://github.com/openfga/language).

docs/validation/model/TROUBLESHOOTING_GUIDE.md

@@ -0,0 +1,182 @@
+# OpenFGA Validation Error Troubleshooting Guide
+
+This guide provides quick solutions to common OpenFGA validation errors. For detailed documentation on each error, see the individual error documents linked below.
+
+## Quick Reference
+
+### Most Common Errors
+
+| Error | Quick Fix | Link |
+|-------|-----------|------|
+| `schema-version-required` | Add `schema 1.1` after `model` | [Details](./schema-version-required.md) |
+| `undefined-relation` | Define the missing relation or fix typo | [Details](./undefined-relation.md) |
+| `undefined-type` | Define the missing type or fix typo | [Details](./undefined-type.md) |
+| `invalid-name` | Use lowercase with underscores only | [Details](./invalid-name.md) |
+| `duplicated-error` | Remove or rename duplicate definitions | [Details](./duplicated-error.md) |
+
+### Schema and Structure Issues
+
+| 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) |
+| `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) |
+
+### Relationship and Reference Errors
+
+| Error | Quick Fix | Link |
+|-------|-----------|------|
+| `relation-no-entry-point` | Add `[user]` or direct assignment | [Details](./relation-no-entry-point.md) |
+| `cyclic-relation` | Break circular references | [Details](./cyclic-relation.md) |
+| `invalid-relation-type` | Fix `type#relation` syntax | [Details](./invalid-relation-type.md) |
+| `tupleuserset-not-direct` | Add direct assignment to tupleset relation | [Details](./tupleuserset-not-direct.md) |
+
+### Naming and Keyword Issues
+
+| Error | Quick Fix | Link |
+|-------|-----------|------|
+| `self-error` | Don't use `self` or `this` as names | [Details](./self-error.md) |
+| `reserved-type-keywords` | Use different type names | [Details](./reserved-type-keywords.md) |
+| `reserved-relation-keywords` | Use different relation names | [Details](./reserved-relation-keywords.md) |
+
+### Wildcard and Advanced Features
+
+| Error | Quick Fix | Link |
+|-------|-----------|------|
+| `invalid-wildcard-error` | Use correct `[type:*]` syntax | [Details](./invalid-wildcard-error.md) |
+| `type-wildcard-relation` | Don't mix wildcard with relation | [Details](./type-wildcard-relation.md) |
+
+### 🎯 Condition Errors
+
+| Error | Quick Fix | Link |
+|-------|-----------|------|
+| `condition-not-defined` | Define the missing condition | [Details](./condition-not-defined.md) |
+| `condition-not-used` | Remove unused condition or use it | [Details](./condition-not-used.md) |
+| `different-nested-condition-name` | Fix condition name consistency | [Details](./different-nested-condition-name.md) |
+
+### Multi-file and Module Errors
+
+| Error | Quick Fix | Link |
+|-------|-----------|------|
+| `multiple-modules-in-file` | Split into separate files | [Details](./multiple-modules-in-file.md) |
+
+## 🛠️ Step-by-Step Troubleshooting
+
+### 1. **Start with Schema Issues**
+```bash
+# Check for these first - they prevent other validation
+- Missing or invalid schema version
+- Incorrect model structure
+- Basic syntax errors
+```
+
+### 2. **Fix Naming Problems**
+```bash
+# Common naming issues to check
+- Type/relation names with uppercase, spaces, or special characters
+- Use of reserved keywords like 'self', 'this', 'model'
+- Names starting with numbers
+```
+
+### 3. **Resolve Reference Issues**
+```bash
+# Check all references exist
+- Types referenced in relations exist
+- Relations referenced in computed usersets exist
+- Conditions referenced in relations exist
+```
+
+### 4. **Address Structural Problems**
+```bash
+# Check authorization model structure
+- Relations have entry points (direct assignments)
+- No circular dependencies
+- Proper tuple-to-userset structure
+```
+
+## Emergency Fixes
+
+### **Model Won't Parse at All**
+```
+1. Check schema declaration: `model` followed by `schema 1.1`
+2. Verify indentation (2 spaces per level)
+3. Check for typos in keywords: `type`, `relations`, `define`
+```
+
+### **Multiple Undefined Errors**
+```
+1. Look for typos in type/relation names
+2. Check case sensitivity (use lowercase)
+3. Verify all referenced types are defined
+```
+
+### **Authorization Not Working**
+```
+1. Check for `relation-no-entry-point` errors
+2. Verify direct assignments exist: `[user]`
+3. Look for circular dependencies
+```
+
+## Validation Checklist
+
+Before deploying your authorization model, verify:
+
+- [ ] Schema version is specified (`schema 1.1`)
+- [ ] All type names use lowercase and underscores
+- [ ] All relation names use lowercase and underscores
+- [ ] No reserved keywords used as names
+- [ ] All referenced types exist
+- [ ] All referenced relations exist
+- [ ] Every relation has an entry point
+- [ ] No circular dependencies
+- [ ] Conditions are defined if used
+- [ ] Multi-file modules are properly organized
+
+## Best Practices
+
+### **Naming Conventions**
+- Use descriptive, business-oriented names
+- Stick to lowercase with underscores
+- Avoid technical jargon in favor of domain terms
+
+### **Model Structure**
+- Start simple, add complexity gradually
+- Use clear hierarchical relationships
+- Document complex permission logic
+
+### **Testing Strategy**
+- Validate model after each change
+- Test with sample authorization data
+- Use YAML test cases for regression testing
+
+## Advanced Debugging
+
+### **Use The FGA CLI**
+
+You can get the FGA CLI from: https://github.com/openfga/cli
+
+1. [Quick model validation](https://github.com/openfga/cli/#validate-an-authorization-model)
+    ```bash
+    fga model validate your-model.fga
+    ```
+
+2. [Proper validation with tests and expectations](https://github.com/openfga/cli/#run-tests-on-an-authorization-model) 
+    ```bash
+    fga model test your-model.fga --test-file tests.yaml
+    ```
+
+### **Common Pattern Issues**
+- Overly complex nested relationships
+- Missing direct assignments in hierarchies
+- Inconsistent permission patterns
+
+## Getting Help
+
+- **Documentation**: See individual error documents for detailed explanations
+- **Examples**: Check the validation test cases for working examples as well as the OpenFGA [sample stores](https://github.com/openfga/sample-stores).
+- **Community**: [OpenFGA community](https://openfga.dev/community) for advanced use cases
+
+---
+
+*This troubleshooting guide covers the most common validation scenarios. For detailed information about any specific error, click the links to view the comprehensive error documentation.*