ruby-structured-data 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ca854a07f1a996cea65258754927d5e5509cb5bb2f7c618ebb8f0819e30af67
+  data.tar.gz: 798d276145c4da10bfe5df55c3d153a4a9a31d410cf7ea7030aa4d0688df9222
+SHA512:
+  metadata.gz: ca9a62dcf4ab94efd21949cb88e24c300383f614a079ae0018b899898adf965540b8d7f4e1c32c9bb4405310d549387934c9f76c473f0b821d9b855f4e14246e
+  data.tar.gz: a73e49d892971809a478bc8b65b0d690040569870818ce950ea976faa029bfbd7699afa2ac72cc43aa11aa721f5f3953367cfcd84fd1b7cd2669eb286ff5a983

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-14
+
+### Changed
+
+- Rails integration loads automatically from the default `gem "ruby-structured-data"` require. The Railtie registers when Rails is present; framework-only usage requires no extra setup.
+
+## [0.1.0] - 2026-09-11
+
+### Added
+
+- Framework-neutral core Schema.org JSON-LD authoring DSL (`StructuredData.node`, `StructuredData.document`, `StructuredData.ref`, `StructuredData.list`, `StructuredData.enum`, `StructuredData.url`, `StructuredData.text`).
+- Embedded Schema.org vocabulary definition supporting types, properties, multiple inheritance, domain/range metadata, and enumerations.
+- Offline metadata-driven validator supporting `:schema_org`, `:strict`, and `:none` validation modes with DidYouMean suggestions and superseded term detection.
+- Fast, HTML-safe JSON-LD serialization neutralizing `</script>` tags and unicode line/paragraph separators.
+- Vocabulary compiler CLI / Rake task (`bundle exec rake schemaorg:update`) to build vocabulary data from upstream Schema.org JSON-LD definitions.
+- Optional Rails integration:
+  - `StructuredData::Rails::Railtie` configuring Railtie options and view helper loading.
+  - `StructuredData::Rails::Registry` for mapping controller/action endpoints to structured data builders.
+  - `StructuredData::Rails::Renderer` for generating `ActiveSupport::SafeBuffer` JSON-LD `<script>` tags.
+  - `StructuredData::Rails::Helper#structured_data_tag` for view rendering.
+  - `rails generate structured_data:install` generator creating `config/initializers/structured_data.rb`.
+- GitHub Actions CI workflow with Ruby 3.4 matrix, RuboCop, Reek, Bundler Audit, and 100% line/branch RSpec coverage.
+- GitHub Actions Release workflow publishing gems to RubyGems.
+
+[Unreleased]: https://github.com/develoz-com/ruby-structured-data/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/develoz-com/ruby-structured-data/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/develoz-com/ruby-structured-data/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Zaffari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,252 @@
+# Ruby Structured Data (`ruby-structured-data`)
+
+Framework-neutral Ruby gem for authoring, validating, and rendering [Schema.org](https://schema.org) JSON-LD structured data with metadata-driven validation and seamless Rails integration.
+
+## Features
+
+- **Fluent DSL**: Expressive API for authoring nodes, documents, graphs, enums, lists, and references.
+- **Embedded Schema.org Vocabulary**: Built-in vocabulary supporting Schema.org types, properties, inheritance, and enumerations.
+- **Diagnostics & Validation**: Fast, metadata-driven validation with three modes (`:schema_org`, `:strict`, `:none`) featuring DidYouMean suggestions and superseded term checks.
+- **XSS-Safe Serialization**: HTML-safe JSON-LD serialization neutralizing `</script>` breakouts and unicode line/paragraph separators.
+- **Rails Integration**: View helper (`structured_data_tag`), page builder registry (`StructuredData::Rails::Registry`), Railtie configuration, and generator (`rails generate structured_data:install`).
+- **100% Test Coverage**: Full line and branch test coverage enforced via SimpleCov.
+
+---
+
+## Installation
+
+Add the gem to your application's `Gemfile`:
+
+```ruby
+gem "ruby-structured-data"
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install ruby-structured-data
+```
+
+---
+
+## Quickstart
+
+### Authoring Nodes
+
+Create Schema.org entities using `StructuredData.node`:
+
+```ruby
+require "ruby-structured-data"
+
+person = StructuredData.node("Person",
+  id: "https://example.com/people/alice",
+  name: "Alice Smith",
+  job_title: "Software Engineer",
+  url: "https://example.com/alice"
+)
+
+# You can also use a block for structured composition:
+organization = StructuredData.node("Organization", id: "https://example.com/#org") do |org|
+  org.set(:name, "Acme Corp")
+  org.set(:url, "https://example.com")
+  org.set(:founder, person)
+end
+```
+
+### Documents & Graphs
+
+Wrap nodes in a `StructuredData.document`. By default, a document with a single node renders as a single entity with `@context`. Multiple nodes or documents explicitly initialized with `graph: true` render within an `@graph` array:
+
+```ruby
+# Single entity document
+doc = StructuredData.document(organization)
+puts StructuredData.dump(doc, pretty: true)
+# => {
+#      "@context": "https://schema.org",
+#      "@type": "Organization",
+#      "@id": "https://example.com/#org",
+#      "name": "Acme Corp",
+#      "url": "https://example.com",
+#      "founder": {
+#        "@type": "Person",
+#        ...
+#      }
+#    }
+
+# Explicit @graph document
+graph_doc = StructuredData.document(organization, person, graph: true)
+puts StructuredData.dump(graph_doc, pretty: true)
+# => {
+#      "@context": "https://schema.org",
+#      "@graph": [
+#        { "@type": "Organization", ... },
+#        { "@type": "Person", ... }
+#      ]
+#    }
+```
+
+### Value Helpers
+
+- `StructuredData.ref("https://example.com/people/alice")`: Creates an entity reference (`{ "@id": "..." }`).
+- `StructuredData.list("Item 1", "Item 2")`: Wraps ordered items in an `@list`.
+- `StructuredData.enum("InStock", "ItemAvailability")`: Generates a Schema.org enumeration URI.
+- `StructuredData.url("https://example.com")`: Validated URL wrapper.
+- `StructuredData.text("Sample text")`: Text value wrapper.
+
+---
+
+## Schema.org Validation
+
+`StructuredData.validate` validates nodes or documents against Schema.org metadata without making network requests.
+
+### Modes
+
+- `:schema_org` (default): Checks unknown types/properties, warns on superseded terms, and flags incompatible ranges.
+- `:strict`: Treats warnings as errors (such as domain mismatches or superseded terms).
+- `:none`: Bypasses schema validation.
+
+```ruby
+# Validating a node
+result = StructuredData.validate(person, mode: :schema_org)
+
+if result.valid?
+  puts "Valid Schema.org data!"
+else
+  result.errors.each { |err| puts "[ERROR] #{err.message}" }
+  result.warnings.each { |warn| puts "[WARNING] #{warn.message}" }
+end
+
+# Or raise a ValidationError when invalid:
+StructuredData.validate!(person)
+```
+
+---
+
+## Rails Integration
+
+### 1. Install Generator
+
+Run the generator to install the initializer:
+
+```bash
+bin/rails generate structured_data:install
+```
+
+This creates `config/initializers/structured_data.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+StructuredData.configure do |config|
+  # Validation mode: :strict, :schema_org (default), or :none
+  config.validation_mode = :schema_org
+
+  # Output pretty formatted JSON-LD
+  config.pretty = Rails.env.development?
+end
+
+# Register controller/action structured data builders:
+# StructuredData::Rails::Registry.register("landing#index", LandingPageBuilder)
+# StructuredData::Rails::Registry.register("products#show") do |context|
+#   StructuredData.node("Product", name: context.product.name)
+# end
+```
+
+### 2. Registry & Builders
+
+Register structured data builders for specific controller actions:
+
+```ruby
+# Using a block
+StructuredData::Rails::Registry.register("products#show") do |view_context|
+  product = view_context.assigns["product"]
+  StructuredData.node("Product",
+    name: product.name,
+    description: product.description,
+    sku: product.sku
+  )
+end
+
+# Or using a dedicated builder class
+class LandingPageBuilder
+  def self.build(view_context)
+    StructuredData.document(
+      StructuredData.node("WebSite",
+        name: "Acme",
+        url: "https://example.com"
+      )
+    )
+  end
+end
+
+StructuredData::Rails::Registry.register("landing#index", LandingPageBuilder)
+```
+
+### 3. View Helper (`structured_data_tag`)
+
+Render the JSON-LD script tag in your layout or view template (e.g. `app/views/layouts/application.html.erb`):
+
+```erb
+<head>
+  <%= structured_data_tag %>
+</head>
+```
+
+When called without arguments, `structured_data_tag` automatically looks up the registered builder matching `controller_path#action_name`.
+
+You can also pass an explicit node or document:
+
+```erb
+<%= structured_data_tag(@article_schema) %>
+```
+
+Output is marked `html_safe` and wrapped in:
+
+```html
+<script type="application/ld+json">
+{"@context":"https://schema.org","@type":"Product","name":"Widget"}
+</script>
+```
+
+---
+
+## Updating Vocabulary
+
+The embedded vocabulary definitions can be re-compiled from upstream Schema.org releases using the compiler:
+
+```bash
+bundle exec rake schemaorg:update
+```
+
+---
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/develoz-com/ruby-structured-data.git
+cd ruby-structured-data
+bundle install
+```
+
+Run test suite and quality checks:
+
+```bash
+bundle exec rspec    # Run test suite
+bundle exec rubocop  # Run RuboCop linter
+bundle exec reek     # Run Reek code smell detector
+bin/ci               # Run complete CI pipeline (RuboCop, Reek, RSpec, Bundler Audit)
+```
+
+---
+
+## License
+
+This project is available as open source under the terms of the [MIT License](LICENSE.txt).