dcat

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

DCAT.ex is an Elixir implementation of the W3C Data Catalog Vocabulary (DCAT) Version 3 specification. It provides Grax schema structures for creating and manipulating data catalogs, datasets, and data services in the RDF ecosystem.

## Common Development Commands

```bash
# Run the complete quality check pipeline
mix check

# Run tests
mix test                           # Run all tests
mix test test/path/to/test.exs    # Run specific test file
mix test test/path:line_number    # Run specific test at line

# Code quality tools
mix format                         # Format code
mix format --check-formatted      # Check formatting
mix credo                          # Run code analysis
mix dialyzer                       # Run static type analysis

# Documentation
mix docs                           # Generate documentation

# Coverage
mix coveralls.html                 # Generate local coverage report
mix coveralls.github              # GitHub Actions coverage (CI only)
```

## Architecture and Key Patterns

### Grax Schema Hierarchy
The codebase uses Grax schemas with inheritance to model DCAT concepts:
- `DCAT.Resource` - Base class for all DCAT resources with common properties
- `DCAT.Dataset < Resource` - Collections of data with distributions
- `DCAT.Catalog < Dataset` - Curated collections of metadata about resources
- `DCAT.Distribution` - Specific representations/formats of datasets
- `DCAT.DataService` - Operations providing access to datasets

### Vocabulary Dependencies
The project integrates multiple RDF vocabularies through the deps/ directory:
- DCTerms (Dublin Core) - `lib/dcat/deps/dcterms/`
- VCard - `lib/dcat/deps/vcard/`
- SPDX - `lib/dcat/deps/spdx/`
- ODRL - `lib/dcat/deps/odrl/`

### Local Development with RDF Packages
For local development with other RDF.ex packages:
```bash
export RDF_EX_PACKAGES_SRC=LOCAL
```
This switches dependencies to use local versions from ../package_name directories.

## Testing Patterns

Tests use `DCAT.Test.Case` which provides common imports and aliases. Integration tests in `test/example_data_tests/` validate against real W3C DCAT examples from `priv/vocabs/`.

When writing tests:
- Use `==` comparisons with expected results on the right side
- Pattern match only when exact comparison is impractical
- Integration tests should test against real DCAT vocabulary examples

## Code Conventions

### Documentation
- Keep documentation minimal and focused on "why" rather than "what"
- Include references to W3C specifications using "See <URL>" format
- Don't document obvious parameters/returns from names and typespecs
- Use hyphens for lists in documentation

### Grax Schema Definitions
```elixir
schema SchemeName < ParentSchema do
  property :property_name, IRI, required: true
  link :link_name, TargetSchema, card: :many
end
```

### TODO Comments
TODO comments are allowed and should be preserved unless the issue is resolved.

## Key Files and Modules

- `lib/dcat.ex` - Main DCAT vocabulary namespace module
- `lib/dcat/resource.ex` - Base resource class with common DCAT properties
- `lib/dcat/dataset.ex` - Dataset schema implementation
- `lib/dcat/catalog.ex` - Catalog schema implementation
- `lib/dcat/ns.ex` - Namespace definitions for all vocabularies
- `priv/vocabs/` - RDF vocabulary files (TTL and NT formats)