refactor: rename schema title to name with format validation

- Renamed schema 'title' to 'name' to align with JSON Schema standards
- Added validation for schema name to ensure it matches the pattern ^[a-zA-Z0-9_-]+$
- Updated all tests and examples to use name instead of title
- Bumped version to 0.3.4

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>

Author: kieranklaassen

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.4] - 2025-03-19
+
+### Changed
+
+- Renamed schema `title` to `name` to align with JSON Schema standards
+- Added validation for schema name to ensure it matches the pattern `^[a-zA-Z0-9_-]+$`
+
 ## [0.3.3] - 2025-03-19
 
 ### Fixed

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    structify (0.3.2)
+    structify (0.3.4)
       activesupport (>= 7.0, < 9.0)
       attr_json (~> 2.1)
 

README.md

@@ -94,7 +94,7 @@ class Article < ApplicationRecord
 
   schema_definition do
     version 1
-    title "Article Extraction"
+    name "ArticleExtraction"
 
     field :title, :string, required: true
     field :summary, :text

lib/structify/model.rb

@@ -111,11 +111,11 @@ def extraction_version
   class SchemaBuilder
     # @return [Class] The model class
     # @return [Array<Hash>] The field definitions
-    # @return [String] The schema title
+    # @return [String] The schema name
     # @return [String] The schema description
     # @return [Integer] The schema version
     # @return [Boolean] Whether thinking mode is enabled
-    attr_reader :model, :fields, :title_str, :description_str, :version_number, :thinking_enabled
+    attr_reader :model, :fields, :name_str, :description_str, :version_number, :thinking_enabled
 
     # Initialize a new SchemaBuilder
     #
@@ -136,12 +136,16 @@ def thinking(enabled)
       @thinking_enabled = enabled
     end
 
-    # Set the schema title
+    # Set the schema name
     #
-    # @param name [String] The title
+    # @param value [String] The name
     # @return [void]
-    def title(name)
-      @title_str = name
+    def name(value)
+      # Validate the name pattern (must match ^[a-zA-Z0-9_-]+$)
+      unless value =~ /^[a-zA-Z0-9_-]+$/
+        raise ArgumentError, "Schema name must only contain alphanumeric characters, underscores, and hyphens"
+      end
+      @name_str = value
     end
 
     # Set the schema description

lib/structify/schema_serializer.rb

@@ -131,7 +131,7 @@ def to_json_schema
       end
 
       {
-        name: schema_builder.title_str,
+        name: schema_builder.name_str,
         description: schema_builder.description_str,
         parameters: {
           type: "object",

lib/structify/version.rb

@@ -1,3 +1,3 @@
 module Structify
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 end

spec/structify/model_spec.rb

@@ -26,7 +26,7 @@
   describe ".schema_definition" do
     it "allows defining a schema with all available options" do
       model_class.schema_definition do
-        title "Article Extraction"
+        name "ArticleExtraction"
         description "Extract article metadata"
         version 2
 
@@ -38,12 +38,52 @@
       expect(model_class.schema_builder).to be_a(Structify::SchemaBuilder)
       expect(model_class.extraction_version).to eq(2)
     end
+    
+    it "validates schema name format" do
+      # Valid names
+      expect {
+        model_class.schema_definition do
+          name "ValidName"
+        end
+      }.not_to raise_error
+      
+      expect {
+        model_class.schema_definition do
+          name "valid_name_with_underscores"
+        end
+      }.not_to raise_error
+      
+      expect {
+        model_class.schema_definition do
+          name "valid-name-with-hyphens"
+        end
+      }.not_to raise_error
+      
+      expect {
+        model_class.schema_definition do
+          name "valid123_with_numbers"
+        end
+      }.not_to raise_error
+      
+      # Invalid names with spaces or special characters
+      expect {
+        model_class.schema_definition do
+          name "Invalid Name With Spaces"
+        end
+      }.to raise_error(ArgumentError, /Schema name must only contain alphanumeric characters/)
+      
+      expect {
+        model_class.schema_definition do
+          name "invalid!name@with#special$chars"
+        end
+      }.to raise_error(ArgumentError, /Schema name must only contain alphanumeric characters/)
+    end
   end
 
   describe ".json_schema" do
     before do
       model_class.schema_definition do
-        title "Article Extraction"
+        name "ArticleExtraction"
         description "Extract article metadata"
         field :title, :string, required: true
         field :summary, :text, description: "A brief summary"
@@ -54,7 +94,7 @@
     it "generates a valid JSON schema" do
       schema = model_class.json_schema
 
-      expect(schema[:name]).to eq("Article Extraction")
+      expect(schema[:name]).to eq("ArticleExtraction")
       expect(schema[:description]).to eq("Extract article metadata")
       expect(schema[:parameters]).to be_a(Hash)
       expect(schema[:parameters][:required]).to eq(["title"])
@@ -69,7 +109,7 @@
           include Structify::Model
 
           schema_definition do
-            title "Article Extraction with Thinking"
+            name "ArticleExtractionThinking"
             description "Extract article metadata with chain of thought"
             thinking true
             field :title, :string, required: true
@@ -406,7 +446,7 @@
 
     it "defaults to version 1 if not specified" do
       model_class.schema_definition do
-        title "Test"
+        name "Test"
       end
 
       expect(model_class.extraction_version).to eq(1)
@@ -422,7 +462,7 @@
           # Define version 1 schema
           schema_definition do
             version 1
-            title "Article Extraction V1"
+            name "ArticleExtractionV1"
 
             field :title, :string
             field :category, :string
@@ -440,7 +480,7 @@
           # Define version 2 schema with additional fields
           schema_definition do
             version 2
-            title "Article Extraction V2"
+            name "ArticleExtractionV2"
 
             # Fields from version 1
             field :title, :string, versions: 1..999
@@ -463,7 +503,7 @@
           # Define version 3 schema with simplified lifecycle syntax
           schema_definition do
             version 3
-            title "Article Extraction V3"
+            name "ArticleExtractionV3"
 
             # Fields available in all versions (1..999)
             field :title, :string, versions: 1..999
@@ -491,7 +531,7 @@
 
           schema_definition do
             version 4
-            title "Simplified Versioning Example"
+            name "SimplifiedVersioning"
 
             # All of these syntaxes should work
             field :always_available, :string, versions: 1..999  # From v1 onward

spec/structify/schema_serializer_spec.rb

@@ -12,7 +12,7 @@
 
   let(:schema_builder) do
     builder = Structify::SchemaBuilder.new(model_class)
-    builder.title("Test Schema")
+    builder.name("TestSchema")
     builder.description("Test Description")
     builder.field(:title, :string, required: true, description: "The title")
     builder.field(:category, :string, enum: ["tech", "business"])
@@ -25,7 +25,7 @@
     it "generates a valid JSON schema" do
       schema = serializer.to_json_schema
 
-      expect(schema[:name]).to eq("Test Schema")
+      expect(schema[:name]).to eq("TestSchema")
       expect(schema[:description]).to eq("Test Description")
       expect(schema[:parameters]).to be_a(Hash)
       expect(schema[:parameters][:required]).to eq(["title"])

spec/structify_spec.rb

@@ -13,7 +13,7 @@
       include Structify::Model
 
       schema_definition do
-        title "Test Schema"
+        name "TestSchema"
         description "A test schema"
         version 1
 
@@ -22,7 +22,7 @@
     end
 
     expect(test_class.json_schema).to include(
-      name: "Test Schema",
+      name: "TestSchema",
       description: "A test schema",
       parameters: {
         type: "object",