Skip to content

SHACL

compare_property_shapes 

compare_property_shapes(source_shapes, target_shapes)

Iterates over a list of SHACL PropertyShapes, comparing to a second set of SHACL PropertyShapes across four similarity dimensions:

  1. Path similarity: Fuzzy matching between PropertyShape 'Path' attributes
  2. Semantic similarity: Cosine similarity matching using Azure OpenAI service
  3. Datatype similarity: Compares PropertyShape data-type definitions (numeric, date-time, string types)
  4. Constraint similarity: Compares constraints

Returns ranked PropertyShapes from target list.

Parameters:

Name Type Description Default
source_shapes List[Dict[str, Any]]

List of PropertyShape dictionaries in JSON-LD format

 required
target_shapes List[Dict[str, Any]]

List of PropertyShape dictionaries in JSON-LD format

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing source shape, best matching target shape, and similarity scores across different dimensions. Each dictionary contains:

  • source_shape (Dict[str, Any]): The original PropertyShape
  • best_match (Dict[str, Any]): Most similar PropertyShape from target_shapes
  • similarity_scores (Dict[str, int]): Similarity scores for the most similar PropertyShape; overall weighted similarity and across each similarity dimension

process_attributes_to_shacl_graph async 

process_attributes_to_shacl_graph(attributes, api_key=None, azure_endpoint=None, api_version=None, model=None)

Processes a list of property attributes to generate a SHACL conformant JSON-LD graph.

This async function takes a list of attribute definitions and processes them concurrently using Azure OpenAI to generate SHACL property shapes. All individual JSON-LD results are merged into a single coherent JSON-LD document with combined contexts and graph entries.

Parameters:

Name Type Description Default
attributes List[Dict[str, Any]]

List of dictionaries containing attribute definitions. Each dictionary should follow the same structure as expected by azure_openai_json_to_shacl_async() with 'id', 'name', 'isHierarchy', and 'data' fields.

 required
api_key str

Azure OpenAI API key. If None, will use environment variable or AzureOpenAIClient defaults.

 None
azure_endpoint str

Azure OpenAI endpoint URL. If None, will use environment variable or AzureOpenAIClient defaults.

 None
api_version str

Azure OpenAI API version. If None, will use environment variable or AzureOpenAIClient defaults.

 None
model str

Azure OpenAI model name. If None, will use environment variable or AzureOpenAIClient defaults.

 None

Returns:

Type Description
Dict[str, Any]

Combined JSON-LD document containing: - '@context': Merged context from all individual results - '@graph': List of all property shapes and SKOS concepts from all attributes

Raises:

Type Description
Exception

Any exception from individual azure_openai_json_to_shacl_async calls. Failed tasks are logged but don't stop processing of other attributes.
JSONDecodeError

If individual results cannot be parsed as JSON.

Examples:

>>> attributes = [
...     {'id': '1', 'name': 'Status', 'data': [{'code': 'ACTIVE', 'description': 'Active'}]},
...     {'id': '2', 'name': 'Priority', 'data': [{'code': 'HIGH', 'description': 'High Priority'}]}
... ]
>>> result = await process_attributes_to_shacl_graph(attributes)
>>> len(result['@graph']) >= 4  # At least 2 property shapes + 2 concepts
True
Note

The function uses asyncio.gather() to process all attributes concurrently, which significantly improves performance for large attribute lists. Failed individual tasks are logged and skipped rather than failing the entire operation.

validate_json_ld 

validate_json_ld(data)

Validate that the provided data is valid JSON-LD with expected SHACL structure.

This function performs comprehensive validation of JSON-LD data to ensure it conforms to the expected structure for SHACL property shapes. It checks for required JSON-LD elements like '@context' and '@graph'/'@id', and verifies the presence of SHACL-specific type information.

Parameters:

Name Type Description Default
data Any

Data to validate. Can be a JSON string or pre-parsed dictionary. Expected to contain JSON-LD formatted SHACL property shapes.

 required

Returns:

Name Type Description
bool bool

True if data is valid JSON-LD with SHACL elements, False otherwise. Returns False if data is not a dictionary, missing required JSON-LD elements, or lacks SHACL Shape type information.

Raises:

Type Description
JSONDecodeError

If data is a string that cannot be parsed as JSON.

Examples:

>>> valid_data = {
...     "@context": {"sh": "http://www.w3.org/ns/shacl#"},
...     "@graph": [{"@type": "sh:PropertyShape", "@id": "ex:prop"}]
... }
>>> validate_json_ld(valid_data)
True
>>> validate_json_ld({"no_context": "value"})
False
Note

The function logs specific validation failures for debugging purposes using the logging module at ERROR level.