Refactor Schema Library Documentation and Examples

- Updated architecture documentation to reflect changes in the Schema class structure, including the removal of file management responsibilities and the introduction of new CRUD operations.
- Revised basic schema example to align with the new API, including changes to member type assignments and serialization methods.
- Enhanced schema editor documentation by streamlining features and improving clarity on user interface elements and functionalities.
- Adjusted getting started guide to accommodate updates in library usage, including NuGet installation instructions and schema serialization.
- Improved consistency in code examples across documentation, ensuring usage of new methods and types introduced in recent updates.

Author: matt-edmondson

README.md

@@ -42,33 +42,34 @@ using ktsu.Schema.Models;
 using ktsu.Schema.Models.Names;
 using ktsu.Schema.Models.Types;
 using ktsu.Semantics.Strings;
+using SchemaTypes = ktsu.Schema.Models.Types;
 
 // Create a new schema
-var schema = new Schema();
+Schema schema = new();
 
 // Add an enum
-var roleEnum = schema.AddEnum("UserRole".As<EnumName>());
+SchemaEnum? roleEnum = schema.AddEnum("UserRole".As<EnumName>());
 roleEnum?.TryAddValue("Admin".As<EnumValueName>());
 roleEnum?.TryAddValue("User".As<EnumValueName>());
 roleEnum?.TryAddValue("Guest".As<EnumValueName>());
 
 // Add a class with typed members
-var userClass = schema.AddClass("User".As<ClassName>());
+SchemaClass? userClass = schema.AddClass("User".As<ClassName>());
 if (userClass != null)
 {
-    var id = userClass.AddMember("Id".As<MemberName>());
+    SchemaMember? id = userClass.AddMember("Id".As<MemberName>());
     id?.SetType(new SchemaTypes.Int());
 
-    var name = userClass.AddMember("Name".As<MemberName>());
+    SchemaMember? name = userClass.AddMember("Name".As<MemberName>());
     name?.SetType(new SchemaTypes.String());
 
-    var email = userClass.AddMember("Email".As<MemberName>());
+    SchemaMember? email = userClass.AddMember("Email".As<MemberName>());
     email?.SetType(new SchemaTypes.String());
 
-    var role = userClass.AddMember("Role".As<MemberName>());
+    SchemaMember? role = userClass.AddMember("Role".As<MemberName>());
     role?.SetType(new SchemaTypes.Enum { EnumName = "UserRole".As<EnumName>() });
 
-    var createdAt = userClass.AddMember("CreatedAt".As<MemberName>());
+    SchemaMember? createdAt = userClass.AddMember("CreatedAt".As<MemberName>());
     createdAt?.SetType(new SchemaTypes.DateTime());
 }
 ```
@@ -77,22 +78,22 @@ if (userClass != null)
 
 ```csharp
 // Add a Project class
-var projectClass = schema.AddClass("Project".As<ClassName>());
-var projectId = projectClass?.AddMember("Id".As<MemberName>());
+SchemaClass? projectClass = schema.AddClass("Project".As<ClassName>());
+SchemaMember? projectId = projectClass?.AddMember("Id".As<MemberName>());
 projectId?.SetType(new SchemaTypes.Int());
-var projectName = projectClass?.AddMember("Name".As<MemberName>());
+SchemaMember? projectName = projectClass?.AddMember("Name".As<MemberName>());
 projectName?.SetType(new SchemaTypes.String());
 
 // Add an array of projects to the User class
-var projects = userClass?.AddMember("Projects".As<MemberName>());
+SchemaMember? projects = userClass?.AddMember("Projects".As<MemberName>());
 projects?.SetType(new SchemaTypes.Array
 {
     ElementType = new SchemaTypes.Object { ClassName = "Project".As<ClassName>() },
     Container = "vector".As<ContainerName>()
 });
 
 // Use a keyed collection (map)
-var projectsMap = userClass?.AddMember("ProjectsById".As<MemberName>());
+SchemaMember? projectsMap = userClass?.AddMember("ProjectsById".As<MemberName>());
 projectsMap?.SetType(new SchemaTypes.Array
 {
     ElementType = new SchemaTypes.Object { ClassName = "Project".As<ClassName>() },
@@ -108,21 +109,34 @@ projectsMap?.SetType(new SchemaTypes.Array
 schema.AddClass(typeof(MyExistingClass));
 ```
 
+### Serialize and Deserialize
+
+```csharp
+// Serialize to JSON
+string json = SchemaSerializer.Serialize(schema);
+
+// Deserialize from JSON (automatically calls Reassociate())
+if (SchemaSerializer.TryDeserialize(json, out Schema? loaded))
+{
+    Console.WriteLine($"Loaded {loaded.Classes.Count} classes");
+}
+```
+
 ### Query the Schema
 
 ```csharp
 // Retrieve classes and enums
-if (schema.TryGetClass("User".As<ClassName>(), out var userClass))
+if (schema.TryGetClass("User".As<ClassName>(), out SchemaClass? foundClass))
 {
-    foreach (var member in userClass.Members)
+    foreach (SchemaMember member in foundClass.Members)
     {
         Console.WriteLine($"  {member.Name}: {member.Type.DisplayName}");
     }
 }
 
-if (schema.TryGetEnum("UserRole".As<EnumName>(), out var roleEnum))
+if (schema.TryGetEnum("UserRole".As<EnumName>(), out SchemaEnum? foundEnum))
 {
-    foreach (var value in roleEnum.Values)
+    foreach (EnumValueName value in foundEnum.Values)
     {
         Console.WriteLine($"  {value}");
     }
@@ -163,39 +177,43 @@ Convert strings using the `.As<T>()` extension method: `"User".As<ClassName>()`
 
 ## JSON Serialization
 
-Schemas serialize to JSON using `System.Text.Json` with polymorphic type discrimination. The `TypeName` property identifies concrete types:
+Use `SchemaSerializer` for JSON serialization with `System.Text.Json`. The serializer uses camelCase property names and polymorphic type discrimination via the `TypeName` discriminator:
 
 ```json
 {
-    "Classes": [
+  "classes": [
+    {
+      "name": "User",
+      "description": "",
+      "members": [
         {
-            "Name": "User",
-            "Members": [
-                {
-                    "Name": "Id",
-                    "Type": { "TypeName": "Int" }
-                },
-                {
-                    "Name": "Role",
-                    "Type": { "TypeName": "Enum", "EnumName": "UserRole" }
-                }
-            ]
-        }
-    ],
-    "Enums": [
+          "name": "Id",
+          "description": "",
+          "type": { "TypeName": "Int" },
+          "memberDescription": ""
+        },
         {
-            "Name": "UserRole",
-            "Values": [
-                { "Name": "Admin" },
-                { "Name": "User" },
-                { "Name": "Guest" }
-            ]
+          "name": "Role",
+          "description": "",
+          "type": { "TypeName": "Enum", "enumName": "UserRole" },
+          "memberDescription": ""
         }
-    ]
+      ]
+    }
+  ],
+  "enums": [
+    {
+      "name": "UserRole",
+      "description": "",
+      "values": ["Admin", "User", "Guest"]
+    }
+  ],
+  "dataSources": [],
+  "codeGenerators": []
 }
 ```
 
-After deserialization, call `schema.Reassociate()` to re-establish parent-child relationships.
+`SchemaSerializer.TryDeserialize()` automatically calls `Reassociate()` to re-establish parent-child relationships after deserialization.
 
 ## Schema Editor
 
@@ -228,15 +246,6 @@ dotnet test
 dotnet build Schema/Schema.csproj
 ```
 
-## Documentation
-
-Detailed documentation is available in the [docs/](docs/) folder:
-
-- [Getting Started](docs/getting-started.md) - Installation and first schema
-- [Basic Schema Example](docs/examples/basic-schema.md) - Complete walkthrough
-- [Architecture](docs/development/architecture.md) - Design patterns and data flow
-- [Schema Editor Guide](docs/features/schema-editor.md) - Visual editor usage
-
 ## License
 
 This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.

docs/development/architecture.md

@@ -75,64 +75,64 @@ This document provides a high-level overview of the Schema library architecture,
 ### Schema (Root Container)
 
 ```csharp
-public partial class Schema
+public class Schema
 {
-    // Collections of schema elements
+    // Collections of schema elements (read-only public API)
     public IReadOnlyCollection<SchemaClass> Classes { get; }
     public IReadOnlyCollection<SchemaEnum> Enums { get; }
     public IReadOnlyCollection<DataSource> DataSources { get; }
-
-    // File management
-    public AbsoluteFilePath FilePath { get; }
-    public SchemaPaths RelativePaths { get; }
+    public IReadOnlyCollection<SchemaCodeGenerator> CodeGenerators { get; }
 
     // CRUD operations
     public SchemaClass? AddClass(ClassName name);
     public bool TryGetClass(ClassName name, out SchemaClass? schemaClass);
-    // ... similar for Enums, DataSources
+    // ... similar for Enums, DataSources, CodeGenerators
 }
 ```
 
 **Responsibilities:**
 
 -   Container for all schema elements
--   File I/O operations (load/save)
--   Element lifecycle management
--   Cross-reference validation
+-   Element lifecycle management (add, get, remove)
+-   Parent-child relationship management via `Reassociate()`
+-   Type queries across all classes
 
 ### Schema Elements Hierarchy
 
 ```
-SchemaChild<T> (Abstract Base)
+SchemaChild<T> (Abstract Base - has Name, Description, ParentSchema)
 ├── SchemaClass : SchemaChild<ClassName>
 ├── SchemaEnum : SchemaChild<EnumName>
 ├── DataSource : SchemaChild<DataSourceName>
 └── SchemaCodeGenerator : SchemaChild<CodeGeneratorName>
 
-SchemaMemberChild<T> (Abstract Base)
-└── SchemaTypes.BaseType : SchemaMemberChild<BaseTypeName>
-    ├── Primitive Types (Int, String, Bool, etc.)
-    ├── Vector Types (Vector2, Vector3, etc.)
-    ├── Complex Types (Array, Object, Enum)
-    └── System Types (DateTime, TimeSpan)
+SchemaClassChild<T> : SchemaChild<T> (adds ParentClass)
+└── SchemaMember : SchemaClassChild<MemberName>
+    └── Contains: BaseType (via Type property, set with SetType())
 
-SchemaMember : SchemaMemberChild<MemberName>
-└── Contains: SchemaTypes.BaseType
+BaseType : IEquatable<BaseType?> (standalone hierarchy, not SchemaChild)
+├── Primitive Types: Int, Long, Float, Double, String, Bool
+├── Temporal Types: DateTime, TimeSpan
+├── Vector Types: Vector2, Vector3, Vector4, ColorRGB, ColorRGBA
+├── Complex Types: Array, Object, Enum
+└── Special: None
 ```
 
 ### Type System Architecture
 
-The type system is built around a polymorphic hierarchy:
+The type system is built around a polymorphic hierarchy using `System.Text.Json`:
 
 ```csharp
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "TypeName")]
-public abstract class BaseType : SchemaMemberChild<BaseTypeName>
+[JsonDerivedType(typeof(Int), nameof(Int))]
+// ... derived type registrations for all types
+public abstract class BaseType : IEquatable<BaseType?>
 {
-    // Core type functionality
-    public abstract string DisplayName { get; }
-    public bool IsBuiltIn { get; }
-    public bool IsPrimitive { get; }
-    // ... type classification properties
+    public SchemaMember? ParentMember { get; } // [JsonIgnore]
+    public string DisplayName { get; }         // [JsonIgnore]
+    public bool IsBuiltIn { get; }             // [JsonIgnore]
+    public bool IsPrimitive { get; }           // [JsonIgnore]
+    // ... type classification properties (all JsonIgnore)
 }
 ```
 
@@ -142,20 +142,23 @@ public abstract class BaseType : SchemaMemberChild<BaseTypeName>
 -   **Type Classification**: Properties like `IsBuiltIn`, `IsPrimitive` for runtime decisions
 -   **Extensibility**: New types can be added by inheriting from `BaseType`
 
-### Strong String Types
+### Semantic String Types
+
+Uses `ktsu.Semantics.Strings` for type-safe identifiers:
 
 ```csharp
-public sealed record class ClassName : StrongStringAbstract<ClassName> { }
-public sealed record class MemberName : StrongStringAbstract<MemberName> { }
-public sealed record class EnumName : StrongStringAbstract<EnumName> { }
-// ... etc
+// Name types implement SemanticString<T> and marker interfaces
+// ClassName, MemberName, EnumName, EnumValueName, etc.
+
+// Convert strings using the .As<T>() extension
+ClassName name = "User".As<ClassName>();
 ```
 
 **Benefits:**
 
 -   Compile-time prevention of parameter confusion
--   Implicit conversion from strings via `.As<T>()` extension
--   JSON serialization as plain strings
+-   Conversion from strings via `.As<T>()` extension
+-   JSON serialization as plain strings (via `RoundTripStringJsonConverterFactory`)
 -   IntelliSense and refactoring support
 
 ## Design Patterns
@@ -190,20 +193,20 @@ public bool IsNumeric => this switch
 };
 ```
 
-### Observer Pattern (Parent-Child Relationships)
+### Parent-Child Association Pattern
 
 ```csharp
 public abstract class SchemaChild<TName>
 {
-    protected Schema? ParentSchema { get; private set; }
+    [JsonIgnore]
+    public Schema? ParentSchema { get; private set; }
 
-    public void AssociateWith(Schema schema)
-    {
-        ParentSchema = schema;
-    }
+    public void AssociateWith(Schema schema) => ParentSchema = schema;
 }
 ```
 
+After deserialization, `Schema.Reassociate()` re-establishes all parent references. `SchemaSerializer.TryDeserialize()` calls this automatically.
+
 ## Data Flow
 
 ### Schema Creation Flow
@@ -264,9 +267,9 @@ Schema (Root)
 **Key Points:**
 
 -   Schema holds strong references to all elements
--   Elements hold weak references back to schema (via interface)
--   JSON serialization creates temporary object graphs
--   No circular reference issues due to careful design
+-   Elements hold direct references back to schema (via `ParentSchema`)
+-   Parent references are marked `[JsonIgnore]` to prevent circular serialization
+-   `Reassociate()` restores parent references after deserialization
 
 ### Performance Considerations
 
@@ -404,7 +407,6 @@ Schema.Test/
 
 ## See Also
 
--   [Project Structure](project-structure.md) - Detailed code organization
--   [API Reference](../api/) - Public API documentation
--   [Contributing](contributing.md) - Development workflow
--   [Performance](performance.md) - Performance optimization guide
+-   [Getting Started](../getting-started.md) - Basic setup and concepts
+-   [Basic Schema Example](../examples/basic-schema.md) - Complete walkthrough
+-   [Schema Editor](../features/schema-editor.md) - Visual editor usage