svg_conform 0.1.0

data/docs/profiles.adoc

@@ -0,0 +1,547 @@
+= SVG Profiles
+:toc: left
+:toclevels: 3
+:sectlinks:
+:sectanchors:
+:source-highlighter: rouge
+
+== Overview
+
+A **Profile** is a collection of requirements and remediations that define a specific SVG conformance standard. Profiles target specific use cases such as IETF RFC documents, web publishing, or custom organizational standards.
+
+Each profile consists of:
+
+* **Requirements**: Validation checks that determine if an SVG document conforms to the profile
+* **Remediations**: Automatic fixes that can be applied when requirements fail
+* **Configuration**: Profile-specific settings and parameters
+
+== Available profiles
+
+SvgConform includes 5 built-in profiles, each designed for different use cases and compliance standards.
+
+[[svg-1-2-rfc-profile]]
+=== SVG 1.2 RFC profile (`:svg_1_2_rfc`)
+
+**Purpose**: Ensures SVG documents comply with RFC 7996 for IETF technical publications.
+
+**Target use case**: Technical diagrams, network diagrams, protocol illustrations for IETF RFCs and Internet-Drafts.
+
+**Key Characteristics**:
+* **Black and white only**: Colors restricted to grayscale per RFC 6949
+* **Limited element set**: Only essential SVG elements allowed (16 total)
+* **Generic fonts only**: serif, sans-serif, monospace families
+* **Self-contained**: No external references permitted
+* **Structured markup**: Proper namespaces and viewBox required
+
+**Requirements**:
+[source,yaml]
+----
+requirements:
+  - allowed_elements      # 16 SVG elements + specific attributes
+  - color_restrictions    # Black, white, #000000, #ffffff only
+  - font_family          # serif, sans-serif, monospace only
+  - namespace_validation # SVG namespace required
+  - namespace_attributes # Only SVG/XLink/XML namespaces
+  - viewbox_required     # viewBox attribute mandatory
+  - style                # CSS style validation
+  - style_promotion      # Detect promotable styles
+  - forbidden_content    # No scripts, multimedia, animation
+  - id_references        # Valid ID references required
+  - link_validation      # ASCII-only links
+----
+
+See link:requirements.adoc#allowed-elements-requirement[AllowedElementsRequirement], link:requirements.adoc#color-restrictions-requirement[ColorRestrictionsRequirement], link:requirements.adoc#font-family-requirement[FontFamilyRequirement], link:requirements.adoc#namespace-requirement[NamespaceRequirement], link:requirements.adoc#namespace-attributes-requirement[NamespaceAttributesRequirement], link:requirements.adoc#viewbox-required-requirement[ViewboxRequiredRequirement], link:requirements.adoc#style-requirement[StyleRequirement], link:requirements.adoc#style-promotion-requirement[StylePromotionRequirement], link:requirements.adoc#forbidden-content-requirement[ForbiddenContentRequirement], link:requirements.adoc#id-reference-requirement[IdReferenceRequirement], and link:requirements.adoc#link-validation-requirement[LinkValidationRequirement] for detailed requirement information.
+
+**Remediations**:
+[source,yaml]
+----
+remediations:
+  - color_conversion     # Convert colors → black/white
+  - font_family_conversion # Map fonts → generic families
+  - style_promotion      # Promote styles → attributes
+  - viewbox_generation   # Add missing viewBox
+----
+
+See link:remediation.adoc#color-remediation[ColorRemediation], link:remediation.adoc#font-remediation[FontRemediation], link:remediation.adoc#style-promotion-remediation[StylePromotionRemediation], and link:remediation.adoc#viewbox-remediation[ViewboxRemediation] for detailed remediation information.
+
+**RFC Compliance**: RFC 7996 (SVG 1.2 specification for RFCs), RFC 6949 (monochromatic requirement)
+
+**SVGCheck Compatibility**: 100% - Perfect error report matching with Python svgcheck tool
+
+**RDF Metadata Handling**: Strict - RDF namespace errors are generated for user awareness but filtered for svgcheck compatibility. For permissive RDF handling, use link:#svg-1-2-rfc-with-rdf-profile[`svg_1_2_rfc_with_rdf`].
+
+**Configuration Features**:
+- `skip_foreign_namespaces: true` - Generic namespace skipping
+- `allow_rdf_metadata: false` - Strict RDF validation
+- Recursive structural invalidity tracking
+
+[[svg-1-2-rfc-with-rdf-profile]]
+=== SVG 1.2 RFC with RDF profile (`:svg_1_2_rfc_with_rdf`)
+
+**Purpose**: Ensures SVG documents comply with RFC 7996 while permissively allowing RDF/Dublin Core metadata.
+
+**Target use case**: Technical diagrams exported from design tools (Inkscape, Illustrator) that embed RDF metadata, while maintaining RFC 7996 conformance for SVG content.
+
+**Key Characteristics**:
+* **Black and white only**: Colors restricted to grayscale per RFC 6949
+* **Limited element set**: Only essential SVG elements allowed (16 total)
+* **Generic fonts only**: serif, sans-serif, monospace families
+* **Self-contained**: No external references permitted
+* **RDF metadata allowed**: Silently accepts RDF/Dublin Core metadata elements
+* **Structured markup**: Proper namespaces and viewBox required
+
+**Requirements**:
+[source,yaml]
+----
+requirements:
+  - allowed_elements      # With allow_rdf_metadata: true
+  - color_restrictions    # Black, white, #000000, #ffffff only
+  - font_family          # serif, sans-serif, monospace only
+  - namespace_validation # SVG namespace + RDF namespaces allowed
+  - namespace_attributes # SVG/XLink/XML namespaces
+  - viewbox_required     # viewBox attribute mandatory
+  - forbidden_content    # No scripts, multimedia, animation
+  - id_references        # Valid ID references required
+  - link_validation      # ASCII-only links
+----
+
+**RDF Namespaces Supported**:
+- `http://www.w3.org/1999/02/22-rdf-syntax-ns#` (RDF)
+- `http://creativecommons.org/ns#` (Creative Commons)
+- `http://purl.org/dc/elements/1.1/` (Dublin Core)
+- `http://purl.org/dc/dcmitype/` (DC MIME types)
+- `http://www.w3.org/2000/01/rdf-schema#` (RDF Schema)
+
+**Remediations**: Same as `svg_1_2_rfc` profile
+
+**RFC Compliance**: RFC 7996/6949 for SVG content, permissive for metadata
+
+**When to Use**:
+* Processing SVG files exported from Inkscape, Adobe Illustrator
+* Accepting design tool metadata while enforcing RFC 7996
+* Workflows where RDF metadata provides useful document information
+* Converting design files to RFC-compliant SVGs without metadata removal
+
+**Comparison with svg_1_2_rfc**:
+
+[cols="2,3,3", options="header"]
+|===
+|Aspect |svg_1_2_rfc (Strict) |svg_1_2_rfc_with_rdf (Permissive)
+
+|RDF Elements
+|Errors generated
+|Silently allowed
+
+|Validation Focus
+|Pure RFC 7996 compliance
+|RFC 7996 + design tool compatibility
+
+|Use Case
+|RFC publication
+|Design tool exports
+
+|Metadata
+|Rejected
+|Accepted (RDF/Dublin Core)
+
+|SVG Content
+|Identical validation
+|Identical validation
+|===
+
+For detailed RDF metadata configuration, see link:rdf_metadata_support.adoc[RDF Metadata Support Documentation].
+
+[[base-profile]]
+=== Base profile (`:base`)
+
+**Purpose**: Provides foundational SVG validation rules common across profiles.
+
+**Target use case**: Starting point for custom profiles, basic SVG structure validation.
+
+**Key Characteristics**:
+* **Namespace validation**: Proper SVG namespace structure
+* **Basic structural checks**: ViewBox, document hierarchy
+* **Foundation for extension**: Other profiles inherit from base
+
+**Requirements**:
+[source,yaml]
+----
+requirements:
+  - namespace_validation # SVG namespace required
+  - viewbox_required     # viewBox recommended
+  - id_references        # Valid references
+----
+
+See link:requirements.adoc#namespace-requirement[NamespaceRequirement], link:requirements.adoc#viewbox-required-requirement[ViewboxRequiredRequirement], and link:requirements.adoc#id-reference-requirement[IdReferenceRequirement] for detailed requirement information.
+
+**Remediations**:
+[source,yaml]
+----
+remediations:
+  - viewbox_generation   # Add viewBox if missing
+  - namespace_fixes      # Fix namespace issues
+----
+
+See link:remediation.adoc#viewbox-remediation[ViewboxRemediation] and link:remediation.adoc#namespace-remediation[NamespaceRemediation] for detailed remediation information.
+
+[[no-external-css-profile]]
+=== No external CSS profile (`:no_external_css`)
+
+**Purpose**: Ensures SVG documents are completely self-contained with no external dependencies.
+
+**Target use case**: Embedded SVG content, email attachments, security-conscious applications.
+
+**Key Characteristics**:
+* **No external references**: Blocks all external CSS, fonts, images
+* **Self-contained documents**: Everything embedded within the SVG
+* **Security focused**: Prevents external resource loading
+
+**Requirements**:
+[source,yaml]
+----
+requirements:
+  - no_external_css     # Block @import, external stylesheets
+  - link_validation     # Validate all link references
+----
+
+See link:requirements.adoc#no-external-css-requirement[NoExternalCssRequirement] and link:requirements.adoc#link-validation-requirement[LinkValidationRequirement] for detailed requirement information.
+
+**Remediations**:
+[source,yaml]
+----
+remediations:
+  - remove_external_css # Strip external CSS references
+----
+
+See link:remediation.adoc#no-external-css-remediation[NoExternalCssRemediation] for detailed remediation information.
+
+**Use Cases**:
+* Email newsletters with embedded SVG
+* Secure document processing
+* Offline applications
+* Content distribution networks
+
+[[lucid-fix-profile]]
+=== Lucid fix profile (`:lucid_fix`)
+
+**Purpose**: Removes Lucid drawing application-specific metadata and attributes.
+
+**Target use case**: Cleaning up SVG exports from Lucid (formerly LucidChart) drawing applications.
+
+**Key Characteristics**:
+* **Namespace cleanup**: Removes `lucid:` namespace attributes
+* **Metadata removal**: Strips Lucid-specific drawing metadata
+* **Standard SVG output**: Produces clean, standard-compliant SVG
+
+**Requirements**:
+[source,yaml]
+----
+requirements:
+  - namespace_attributes # Detect lucid: namespace usage
+----
+
+See link:requirements.adoc#namespace-attributes-requirement[NamespaceAttributesRequirement] for detailed requirement information.
+
+**Remediations**:
+[source,yaml]
+----
+remediations:
+  - namespace_attribute_removal # Remove lucid:* attributes
+----
+
+See link:remediation.adoc#namespace-attribute-remediation[NamespaceAttributeRemediation] for detailed remediation information.
+
+**Specific Fixes**:
+* Removes `xmlns:lucid` declarations
+* Strips `lucid:*` attributes from elements
+* Preserves document structure and appearance
+* Maintains valid SVG markup
+
+[[metanorma-profile]]
+=== Metanorma profile (`:metanorma`)
+
+**Purpose**: Ensures SVG documents comply with Metanorma requirements for technical documents with embedded resources.
+
+**Target use case**: Technical diagrams, flowcharts, and illustrations for Metanorma-generated standards documents (ISO, IEC, IETF, etc.).
+
+**Key Characteristics**:
+* **Flexible colors**: Any colors allowed (unlike RFC 7996 black/white restriction)
+* **Flexible fonts**: Any font families allowed (unlike RFC 7996 generic-only restriction)
+* **Flexible styles**: Any CSS styles allowed
+* **Self-contained resources**: All CSS and fonts must be embedded
+* **Structural compliance**: Proper namespaces and viewBox required
+* **No external dependencies**: External CSS and fonts strictly prohibited
+
+**Requirements**:
+[source,yaml]
+----
+requirements:
+  - allowed_elements      # 16 SVG elements + specific attributes
+  - namespace_validation # SVG namespace required
+  - namespace_attributes # Only SVG/XLink/XML namespaces
+  - viewbox_required     # viewBox attribute mandatory
+  - forbidden_content    # No scripts, multimedia, animation
+  - id_references        # Valid ID references required
+  - link_validation      # ASCII-only links
+  - no_external_css      # External CSS prohibited
+  - no_external_fonts    # External fonts prohibited
+----
+
+See link:requirements.adoc#allowed-elements-requirement[AllowedElementsRequirement], link:requirements.adoc#namespace-requirement[NamespaceRequirement], link:requirements.adoc#namespace-attributes-requirement[NamespaceAttributesRequirement], link:requirements.adoc#viewbox-required-requirement[ViewboxRequiredRequirement], link:requirements.adoc#forbidden-content-requirement[ForbiddenContentRequirement], link:requirements.adoc#id-reference-requirement[IdReferenceRequirement], link:requirements.adoc#link-validation-requirement[LinkValidationRequirement], link:requirements.adoc#no-external-css-requirement[NoExternalCssRequirement], and link:requirements.adoc#no-external-fonts-requirement[NoExternalFontsRequirement] for detailed requirement information.
+
+**Remediations**:
+[source,yaml]
+----
+remediations:
+  - viewbox_generation          # Add missing viewBox
+  - namespace_attribute_cleanup # Remove disallowed namespace attributes
+  - font_embedding             # Detect external fonts (placeholder)
+----
+
+See link:remediation.adoc#viewbox-remediation[ViewboxRemediation], link:remediation.adoc#namespace-attribute-remediation[NamespaceAttributeRemediation], and link:remediation.adoc#font-embedding-remediation[FontEmbeddingRemediation] for detailed remediation information.
+
+**Differences from RFC 7996 Profile**:
+
+[cols="2,3,3", options="header"]
+|===
+|Aspect |svg_1_2_rfc (RFC 7996) |metanorma (Metanorma)
+
+|Colors
+|Black/white only (#000, #fff)
+|Any colors allowed
+
+|Fonts
+|Generic only (serif, sans-serif, monospace)
+|Any fonts allowed
+
+|CSS Styles
+|Restricted property set
+|Any styles allowed
+
+|External CSS
+|Implicitly prohibited
+|Explicitly prohibited with requirement
+
+|External Fonts
+|Not specifically checked
+|Explicitly prohibited with detection
+
+|Use Case
+|RFC publication diagrams
+|Metanorma standards documents
+
+|Target Audience
+|IETF RFC authors
+|ISO, IEC, NIST, ITU standards authors
+|===
+
+**External Resource Policy**:
+* ❌ **External CSS**: Rejected without remediation (cannot be automatically embedded)
+* ⚠️ **External Fonts**: Detected with placeholder remediation (requires manual embedding or future implementation)
+* ✅ **Embedded Fonts**: Supported via data: URIs
+* ✅ **Inline Styles**: Fully supported
+
+**When to Use**:
+* Processing SVG files for Metanorma documents
+* Need color/styled diagrams (unlike RFC 7996)
+* Require self-contained SVG (no external dependencies)
+* Converting design tool exports (Lucid, Draw.io, Inkscape)
+* Publishing standards documents (ISO, IEC, IETF, NIST, ITU, etc.)
+
+**Font Embedding Status**: Detection implemented, full embedding requires additional development. External fonts are flagged as errors, manual conversion to data: URIs is currently required.
+
+== Profile Inheritance and Customization
+
+Profiles support inheritance through the `import` directive:
+
+[source,yaml]
+----
+# config/profiles/my_custom_profile.yml
+name: "Custom Organization Profile"
+description: "Extends base profile with organization rules"
+import: "base"  # Inherit all base profile requirements
+
+# Add additional requirements
+requirements:
+  - id: "custom_colors"
+    type: "ColorRestrictionsRequirement"
+    description: "Allow organization brand colors"
+    allowed_colors: ["black", "white", "#0066cc", "#ff6600"]
+
+# Add specific remediations
+remediations:
+  - id: "brand_color_conversion"
+    type: "ColorRemediation"
+    description: "Convert to brand colors"
+    targets: ["custom_colors"]
+----
+
+=== Configuration Structure
+
+Profiles use a structured YAML configuration format:
+
+[source,yaml]
+----
+profile:
+  name: "Profile Display Name"
+  description: "Brief description of profile purpose"
+  import: "parent_profile"  # Optional inheritance
+
+requirements:
+  - id: "unique_requirement_id"
+    type: "RequirementClassName"
+    description: "Human-readable description"
+    config:                    # Optional configuration
+      parameter: "value"
+      another_param: true
+
+remediations:
+  - id: "unique_remediation_id"
+    type: "RemediationClassName"
+    description: "Human-readable description"
+    targets: ["requirement_id1", "requirement_id2"]  # Which requirements this remediation addresses
+    config:                    # Optional configuration
+      strategy: "remove"
+      default_value: "fallback"
+----
+
+=== Profile Selection Guide
+
+**Choose `svg_1_2_rfc` when**:
+* Creating technical diagrams for IETF documents
+* Need RFC 7996/6949 compliance
+* Require black and white output
+* Need maximum compatibility
+
+**Choose `no_external_css` when**:
+* Embedding SVG in emails or secure contexts
+* Require fully self-contained documents
+* Security is a primary concern
+* Offline usage is required
+
+**Choose `lucid_fix` when**:
+* Processing SVG exports from Lucid applications
+* Need to remove application-specific metadata
+* Want clean, standard SVG output
+
+**Choose `base` when**:
+* Building custom profiles
+* Need minimal validation rules
+* Want foundational structure checking
+* Creating organization-specific profiles
+
+== Custom Profiles
+
+You can create custom profiles by defining YAML configuration files:
+
+[source,yaml]
+----
+# config/profiles/my_profile.yml
+profile:
+  name: "My Custom Profile"
+  description: "Custom SVG profile for my organization"
+  import: "base"  # Optional: inherit from another profile
+
+requirements:
+  - type: "NamespaceRequirement"
+    id: "svg_namespace"
+    description: "Ensure proper SVG namespace"
+    config:
+      required_namespace: "http://www.w3.org/2000/svg"
+
+  - type: "ViewboxRequiredRequirement"
+    id: "viewbox_required"
+    description: "Require viewBox attribute"
+
+  - type: "NoExternalCssRequirement"
+    id: "no_external_css"
+    description: "Prevent external CSS references"
+
+remediations:
+  - type: "NamespaceRemediationAction"
+    id: "fix_namespace"
+    description: "Add missing SVG namespace"
+    targets: ["svg_namespace"]
+
+  - type: "ViewboxRemediationAction"
+    id: "fix_viewbox"
+    description: "Add missing viewBox attribute"
+    targets: ["viewbox_required"]
+----
+
+=== Profile Loading
+
+Profiles can be loaded in several ways:
+
+**From built-in profiles**:
+[source,ruby]
+----
+# Load built-in profile by symbol
+profile = SvgConform::Profile.load(:svg_1_2_rfc)
+
+# Load built-in profile by string
+profile = SvgConform::Profile.load("base")
+----
+
+**From file**:
+[source,ruby]
+----
+# Load custom profile from YAML file
+profile = SvgConform::Profile.load_from_file('config/profiles/my_profile.yml')
+----
+
+**Programmatically**:
+[source,ruby]
+----
+# Create profile programmatically
+profile = SvgConform::Profile.new(
+  name: "Custom Profile",
+  description: "Created programmatically",
+  requirements: [
+    SvgConform::Requirements::NamespaceRequirement.new(id: "namespace", description: "SVG namespace")
+  ],
+  remediations: [
+    SvgConform::Remediations::NamespaceRemediation.new(id: "fix_namespace", targets: ["namespace"])
+  ]
+)
+----
+
+=== Profile Validation
+
+Profiles are validated when loaded to ensure:
+
+* All referenced requirement classes exist
+* All referenced remediation classes exist
+* Remediation targets reference valid requirement IDs
+* Configuration parameters are valid for each component
+* No circular dependencies in profile inheritance
+
+== Best Practices
+
+=== Profile Design
+
+* **Be specific**: Target a particular use case or standard
+* **Use inheritance**: Build on existing profiles when possible
+* **Document thoroughly**: Provide clear descriptions for all components
+* **Test extensively**: Validate with representative SVG files
+
+=== Requirement Selection
+
+* **Choose focused requirements**: Each requirement should validate one concern
+* **Avoid redundancy**: Don't include overlapping requirements
+* **Consider performance**: More requirements mean longer validation time
+* **Think about users**: Include requirements that provide actionable feedback
+
+=== Remediation Configuration
+
+* **Map appropriately**: Ensure remediations target the right requirements
+* **Test remediation results**: Verify fixes don't break document structure
+* **Provide fallbacks**: Consider what happens when remediation fails
+* **Document side effects**: Note any visual or structural changes
+
+=== Profile Maintenance
+
+* **Version your profiles**: Track changes over time
+* **Test with real content**: Use actual SVG files from target use cases
+* **Monitor performance**: Profile complexity affects validation speed
+* **Document updates**: Maintain clear change logs for profile modifications