Universal.Common.Formats.Dtd 1.0.2

Universal.Common.Formats.Dtd

DTD (Document Type Definition) parser for .NET, providing a complete object model for parsing and working with XML DTD files.

⚠️ Security Notice

This library should only be used with trusted DTD files. The parser does not implement protection against:

• Billion laughs attacks (entity expansion attacks)
• Quadratic blowup attacks
• Excessive entity nesting
• Other malicious DTD constructs

Do not use this library to parse DTDs from untrusted sources without implementing additional security controls.

Classes

Document

Represents a complete DTD document, including both internal and external subsets.

var document = new Document
{
    SystemId = "http://example.com/mydtd.dtd",
    PublicId = "-//Example//DTD Example 1.0//EN",
    Declarations = new Declaration[] { /* ... */ }
};

DocumentReader

Parses DTD files from various sources including URIs, streams, and strings. Supports parameter entity expansion and external entity resolution.

// Parse from URI
using (var reader = new DocumentReader())
{
    Document doc = await reader.ReadAsync(new Uri("file:///path/to/file.dtd"));
}

// Parse from stream
using (var stream = File.OpenRead("file.dtd"))
using (var reader = new DocumentReader())
{
    Document doc = await reader.ReadAsync(stream);
}

// Parse from string
using (var reader = new DocumentReader())
{
    Document doc = reader.Parse(dtdContent);
}

// Configure options
var options = new DocumentReader.Options
{
    ExpandParameterEntities = true,
    ExternalParameterEntityResolver = new ExternalParameterEntityResolver()
};
using (var reader = new DocumentReader(options))
{
    Document doc = await reader.ReadAsync(uri);
}

Declaration Types

The library supports all standard DTD declaration types:

ElementDeclaration

Defines element structure and content models.

var element = new ElementDeclaration
{
    Name = "book",
    ContentSpecification = new ElementContentSpecification
    {
        Particle = new SequenceGroupContentParticle
        {
            Particles = new ContentParticle[]
            {
                new ElementReferenceContentParticle { Name = "title" },
                new ElementReferenceContentParticle { Name = "author", Occurrence = OccurrenceIndicator.OneOrMore }
            }
        }
    }
};

AttributeListDeclaration

Defines attributes for elements.

var attlist = new AttributeListDeclaration
{
    ElementName = "book",
    Attributes = new[]
    {
        new AttributeDefinition
        {
            Name = "isbn",
            Type = new CDataAttributeType(),
            Default = new RequiredDefault()
        },
        new AttributeDefinition
        {
            Name = "format",
            Type = new EnumerationAttributeType { Values = new[] { "hardcover", "paperback", "ebook" } },
            Default = new DefaultValueDefault { Value = "paperback" }
        }
    }
};

EntityDeclaration

Defines general and parameter entities.

// Internal entity
var internalEntity = new EntityDeclaration
{
    Name = "copyright",
    Definition = new InternalEntity { Value = "Copyright © 2024" }
};

// External entity
var externalEntity = new EntityDeclaration
{
    Name = "chapter1",
    Definition = new ExternalEntity
    {
        SystemId = "chapter1.xml",
        PublicId = "-//Example//TEXT Chapter 1//EN"
    }
};

// Parameter entity
var parameterEntity = new EntityDeclaration
{
    Name = "commonAttrs",
    IsParameterEntity = true,
    Definition = new InternalEntity { Value = "id ID #IMPLIED" }
};

NotationDeclaration

Declares notations for external data formats.

var notation = new NotationDeclaration
{
    Name = "GIF",
    Definition = new SystemNotation { SystemId = "gif-viewer.exe" }
};

ConditionalSection

Supports INCLUDE and IGNORE conditional sections.

var conditional = new ConditionalSection
{
    Type = ConditionalSectionType.Include,
    Declarations = new Declaration[] { /* ... */ }
};

CommentDeclaration

Represents comments in the DTD.

var comment = new CommentDeclaration
{
    Text = "This is a comment"
};

ProcessingInstructionDeclaration

Represents processing instructions.

var pi = new ProcessingInstructionDeclaration
{
    Target = "xml-stylesheet",
    Data = "type=\"text/xsl\" href=\"style.xsl\""
};

Content Specifications

DTD content models are represented by various specification types:

• EmptyContentSpecification: Element must be empty
• AnyContentSpecification: Element can contain any content
• ElementContentSpecification: Element contains structured child elements
• MixedContentSpecification: Element can contain text and/or child elements

// EMPTY
new EmptyContentSpecification()

// ANY
new AnyContentSpecification()

// Element content: (title, author+)
new ElementContentSpecification
{
    Particle = new SequenceGroupContentParticle
    {
        Particles = new ContentParticle[]
        {
            new ElementReferenceContentParticle { Name = "title" },
            new ElementReferenceContentParticle 
            { 
                Name = "author", 
                Occurrence = OccurrenceIndicator.OneOrMore 
            }
        }
    }
}

// Mixed content: (#PCDATA | emphasis | strong)*
new MixedContentSpecification
{
    Elements = new[] { "emphasis", "strong" }
}

Attribute Types

All XML attribute types are supported:

• CDataAttributeType: Character data
• IdAttributeType: Unique identifier
• IdReferenceAttributeType: Reference to an ID
• IdReferencesAttributeType: Space-separated list of ID references
• EntityAttributeType: Reference to an entity
• EntitiesAttributeType: Space-separated list of entity references
• NameTokenAttributeType: Name token
• NameTokensAttributeType: Space-separated list of name tokens
• EnumerationAttributeType: Enumerated values
• NotationAttributeType: Notation name

Attribute Defaults

Four types of attribute defaults are supported:

• DefaultValueDefault: Provides a default value
• RequiredDefault: Attribute is required (#REQUIRED)
• ImpliedDefault: Attribute is optional (#IMPLIED)
• FixedDefault: Attribute has a fixed value (#FIXED)

ExternalParameterEntityResolver

Resolves external parameter entities with configurable security options.

var options = new ExternalParameterEntityResolver.Options
{
    AllowHttp = false,      // Disallow HTTP for security
    AllowHttps = true,      // Allow HTTPS
    AllowFile = true,       // Allow local files
    AllowedDomains = new HashSet<string> { "example.com", "trusted.org" },
    EnableCaching = true    // Cache resolved entities
};

using (var resolver = new ExternalParameterEntityResolver(options))
{
    var readerOptions = new DocumentReader.Options
    {
        ExpandParameterEntities = true,
        ExternalParameterEntityResolver = resolver
    };
    
    using (var reader = new DocumentReader(readerOptions))
    {
        Document doc = await reader.ReadAsync(uri);
    }
}

OccurrenceIndicator

Defines occurrence indicators for content particles:

• Once: Element appears exactly once (no indicator)
• Optional: Element appears zero or one time (?)
• ZeroOrMore: Element appears zero or more times (*)
• OneOrMore: Element appears one or more times (+)

Usage Examples

Parsing a DTD with DOCTYPE declaration

string dtd = @"
<!DOCTYPE book SYSTEM 'book.dtd' [
    <!ELEMENT book (title, author+)>
    <!ATTLIST book isbn CDATA #REQUIRED>
]>";

using (var reader = new DocumentReader())
{
    Document doc = reader.Parse(dtd);
    
    foreach (var decl in doc.Declarations)
    {
        if (decl is ElementDeclaration elem)
        {
            Console.WriteLine($"Element: {elem.Name}");
        }
    }
}

Parsing an external DTD subset

using (var reader = new DocumentReader())
{
    Document doc = await reader.ReadAsync(
        new Uri("https://example.com/dtds/mydtd.dtd"));
    
    // Process declarations
    var elements = doc.Declarations.OfType<ElementDeclaration>();
    var attributes = doc.Declarations.OfType<AttributeListDeclaration>();
}

Working with parameter entities

var options = new DocumentReader.Options
{
    ExpandParameterEntities = true,
    ExternalParameterEntityResolver = new ExternalParameterEntityResolver(
        new ExternalParameterEntityResolver.Options
        {
            AllowHttps = true,
            AllowFile = true
        })
};

using (var reader = new DocumentReader(options))
{
    Document doc = await reader.ReadAsync(uri);
    // Parameter entities are automatically expanded
}