json_ld/algorithms/context_processing/

mod.rs

//! JSON-LD context processing types and algorithms.
use std::borrow::Cow;

use rdf_syntax::Iri;

mod define;
mod iri;
mod merged;
mod options;
mod stack;

use define::*;
use iri::*;
use merged::Merged;
pub use options::JsonLdContextProcessingOptions;
use stack::ProcessingStack;

use crate::{
	AsyncJsonLdLoader, JsonLdBacktraceBuilder, JsonLdContextDocument, JsonLdError,
	JsonLdLocatedError, JsonLdNullable, JsonLdProcessedContext, JsonLdProcessingMode,
	JsonLdSourceFileRef, JsonLdTerm,
	algorithms::AsyncJsonLdEnvironment,
	context::RawJsonLdProcessedContext,
	syntax::{JsonLdContext, JsonLdContextEntry, JsonLdKeyword, context::JsonLdKeyOrKeywordRef},
};

struct TargetProcessedContext<'a> {
	pub value: &'a mut RawJsonLdProcessedContext,
	pub defined: DefinedTerms,
}

struct ContextProcessor<'a> {
	pub remote_contexts: ProcessingStack,
	pub active_context: &'a RawJsonLdProcessedContext,
	pub base_url: Option<&'a Iri>,
	pub options: JsonLdContextProcessingOptions,
}

impl<'a> ContextProcessor<'a> {
	fn for_recursive_definition<'b>(&'b self) -> ContextProcessor<'b> {
		ContextProcessor {
			remote_contexts: self.remote_contexts.clone(),
			active_context: self.active_context,
			base_url: None,
			options: self.options.with_no_override(),
		}
	}

	fn for_sub_context<'b>(
		&'b self,
		active_context: &'b RawJsonLdProcessedContext,
		base_url: Option<&'b Iri>,
		options: JsonLdContextProcessingOptions,
	) -> ContextProcessor<'b> {
		ContextProcessor {
			remote_contexts: self.remote_contexts.clone(),
			active_context,
			base_url,
			options,
		}
	}
}

impl JsonLdContextDocument {
	/// Process this context with the default options.
	///
	/// See: <https://www.w3.org/TR/json-ld11-api/#context-processing-algorithm>
	pub async fn process(
		&self,
		env: impl AsyncJsonLdEnvironment,
	) -> Result<JsonLdProcessedContext<'_>, JsonLdLocatedError> {
		let loc = JsonLdBacktraceBuilder::new().file(JsonLdSourceFileRef::original(self.url()));
		self.document
			.context
			.process_with(
				env,
				self.url(),
				&RawJsonLdProcessedContext::new(None),
				JsonLdContextProcessingOptions::default(),
				loc,
			)
			.await
	}
}

impl JsonLdContext {
	/// Process this context with the default options.
	///
	/// See: <https://www.w3.org/TR/json-ld11-api/#context-processing-algorithm>
	pub async fn process(
		&self,
		env: impl AsyncJsonLdEnvironment,
		base_url: Option<&Iri>,
	) -> Result<JsonLdProcessedContext<'_>, JsonLdLocatedError> {
		let active_context = RawJsonLdProcessedContext::new(None);
		self.process_with(
			env,
			base_url,
			&active_context,
			JsonLdContextProcessingOptions::default(),
			// No document URL available here; still need a `File` frame or the
			// backtrace would be silently empty.
			JsonLdBacktraceBuilder::new().file(JsonLdSourceFileRef::original(None)),
		)
		.await
	}

	/// Process this context with the given options.
	///
	/// See: <https://www.w3.org/TR/json-ld11-api/#context-processing-algorithm>
	pub async fn process_with(
		&self,
		env: impl AsyncJsonLdEnvironment,
		base_url: Option<&Iri>,
		active_context: &RawJsonLdProcessedContext,
		options: JsonLdContextProcessingOptions,
		location: JsonLdBacktraceBuilder<'_>,
	) -> Result<JsonLdProcessedContext<'_>, JsonLdLocatedError> {
		ContextProcessor {
			options,
			remote_contexts: ProcessingStack::new(),
			base_url,
			active_context,
		}
		.process(&env, self, location)
		.await
		.map(|raw| JsonLdProcessedContext::new(Cow::Borrowed(self), raw))
	}
}

impl<'a> ContextProcessor<'a> {
	async fn process(
		mut self,
		env: &impl AsyncJsonLdEnvironment,
		local_context: &JsonLdContext,
		location: JsonLdBacktraceBuilder<'_>,
	) -> Result<RawJsonLdProcessedContext, JsonLdLocatedError> {
		// 1) Initialize result to the result of cloning active context.
		let mut result = self.active_context.clone();

		// 2) If `local_context` is an object containing the member @propagate,
		// its value MUST be boolean true or false, set `propagate` to that value.
		if let JsonLdContext::One(JsonLdContextEntry::Definition(def)) = local_context
			&& let Some(propagate) = def.propagate
		{
			if self.options.processing_mode == JsonLdProcessingMode::JsonLd1_0 {
				return Err(JsonLdError::InvalidContextEntry.at(location));
			}

			self.options.propagate = propagate
		}

		// 3) If propagate is false, and result does not have a previous context,
		// set previous context in result to active context.
		if !self.options.propagate && result.previous_context().is_none() {
			result.set_previous_context(self.active_context.clone());
		}

		// 4) If local context is not an array, set it to an array containing only local context.
		// 5) For each item context in local context:
		for (i, context) in local_context.iter().enumerate() {
			let entry_loc = location.array_index(i);
			match context {
				// 5.1) If context is null:
				JsonLdContextEntry::Null => {
					// If `override_protected` is false and `active_context` contains any protected term
					// definitions, an invalid context nullification has been detected and processing
					// is aborted.
					if !self.options.override_protected && result.has_protected_items() {
						return Err(JsonLdError::InvalidContextNullification.at(entry_loc));
					} else {
						// Otherwise, initialize result as a newly-initialized active context, setting
						// previous_context in result to the previous value of result if propagate is
						// false. Continue with the next context.
						let previous_result = result;

						// Initialize `result` as a newly-initialized active context, setting both
						// `base_iri` and `original_base_url` to the value of `original_base_url` in
						// active context, ...
						result = RawJsonLdProcessedContext::new(
							self.active_context
								.original_base_url()
								.map(ToOwned::to_owned),
						);

						// ... and, if `propagate` is `false`, `previous_context` in `result` to the
						// previous value of `result`.
						if !self.options.propagate {
							result.set_previous_context(previous_result);
						}
					}
				}

				// 5.2) If context is a string,
				JsonLdContextEntry::IriRef(iri_ref) => {
					// Initialize `context` to the result of resolving context against base URL.
					// If base URL is not a valid IRI, then context MUST be a valid IRI, otherwise
					// a loading document failed error has been detected and processing is aborted.
					let context_iri = resolve_iri(iri_ref, self.base_url)
						.ok_or_else(|| JsonLdError::LoadingDocumentFailed.at(entry_loc))?;

					// If the number of entries in the `remote_contexts` array exceeds a processor
					// defined limit, a context overflow error has been detected and processing is
					// aborted; otherwise, add context to remote contexts.
					//
					// If context was previously dereferenced, then the processor MUST NOT do a further
					// dereference, and context is set to the previously established internal
					// representation: set `context_document` to the previously dereferenced document,
					// and set loaded context to the value of the @context entry from the document in
					// context document.
					//
					// Otherwise, set `context document` to the RemoteDocument obtained by dereferencing
					// context using the LoadDocumentCallback, passing context for url, and
					// http://www.w3.org/ns/json-ld#context for profile and for requestProfile.
					//
					// If context cannot be dereferenced, or the document from context document cannot
					// be transformed into the internal representation , a loading remote context
					// failed error has been detected and processing is aborted.
					// If the document has no top-level map with an @context entry, an invalid remote
					// context has been detected and processing is aborted.
					// Set loaded context to the value of that entry.
					if self.remote_contexts.push(context_iri.clone()) {
						let loaded_context = env
							.loader()
							.async_load(&context_iri)
							.await
							.map_err(|e| JsonLdError::ContextLoadingFailed(e).at(entry_loc))?
							.try_into_context_document()
							.map_err(|e| {
								JsonLdError::RemoteContextSyntax(e.to_string()).at(entry_loc)
							})?
							.into_document()
							.context;

						// Set result to the result of recursively calling this algorithm, passing result
						// for active context, loaded context for local context, the documentUrl of context
						// document for base URL, and a copy of remote contexts.
						let new_options = JsonLdContextProcessingOptions {
							processing_mode: self.options.processing_mode,
							override_protected: false,
							propagate: true,
						};

						// Extend the caller's trace rather than starting a fresh one, so that
						// errors raised while processing `loaded_context` still show which
						// `@context` array slot, in which calling document, pulled it in.
						let remote_loc =
							entry_loc.file(JsonLdSourceFileRef::original(Some(&context_iri)));
						result = Box::pin(
							self.for_sub_context(&result, Some(&context_iri), new_options)
								.process(env, &loaded_context, remote_loc),
						)
						.await?;
					}
				}

				// 5.4) Context definition.
				JsonLdContextEntry::Definition(context) => {
					// 5.5) If context has a @version entry:
					if context.version.is_some() {
						// 5.5.2) If processing mode is set to json-ld-1.0, a processing mode conflict
						// error has been detected.
						if self.options.processing_mode == JsonLdProcessingMode::JsonLd1_0 {
							return Err(JsonLdError::ProcessingModeConflict.at(entry_loc));
						}
					}

					// 5.6) If context has an @import entry:
					let mut import_url = None;
					let import_context = match &context.import {
						Some(import_value) => {
							// 5.6.1) If processing mode is json-ld-1.0, an invalid context entry error
							// has been detected.
							let import_loc = entry_loc.object_value(JsonLdKeyword::Import);

							if self.options.processing_mode == JsonLdProcessingMode::JsonLd1_0 {
								return Err(JsonLdError::InvalidContextEntry.at(import_loc));
							}

							// 5.6.3) Initialize import to the result of resolving the value of
							// @import.
							let import = resolve_iri(import_value, self.base_url)
								.ok_or_else(|| JsonLdError::InvalidImportValue.at(import_loc))?;

							// 5.6.4) Dereference import.
							let import_context = env
								.loader()
								.async_load(&import)
								.await
								.map_err(|e| JsonLdError::ContextLoadingFailed(e).at(import_loc))?
								.try_into_context_document()
								.map_err(|e| {
									JsonLdError::RemoteContextSyntax(e.to_string()).at(import_loc)
								})?
								.into_document()
								.context;

							// If the dereferenced document has no top-level map with an @context
							// entry, or if the value of @context is not a context definition
							// (i.e., it is not an map), an invalid remote context has been
							// detected and processing is aborted; otherwise, set import context
							// to the value of that entry.
							match &import_context {
								JsonLdContext::One(JsonLdContextEntry::Definition(
									import_context_def,
								)) => {
									// If `import_context` has a @import entry, an invalid context entry
									// error has been detected and processing is aborted.
									if import_context_def.import.is_some() {
										return Err(JsonLdError::InvalidContextEntry.at(import_loc));
									}
								}
								_ => {
									return Err(JsonLdError::InvalidRemoteContext.at(import_loc));
								}
							}

							// Set `context` to the result of merging context into
							// `import_context`, replacing common entries with those from
							// `context`.
							import_url = Some(import);
							Some(import_context)
						}
						None => None,
					};

					let context = Merged::new(context, import_context);

					// 5.7) If context has a @base entry and remote contexts is empty, i.e.,
					// the currently being processed context is not a remote context:
					if self.remote_contexts.is_empty() {
						// Initialize value to the value associated with the @base entry.
						if let Some(value) = context.base() {
							match value {
								JsonLdNullable::Null => {
									// If value is null, remove the base IRI of result.
									result.set_base_iri(None);
								}
								JsonLdNullable::Some(iri_ref) => match iri_ref.as_iri() {
									Some(iri) => result.set_base_iri(Some(iri.to_owned())),
									None => {
										let resolved = resolve_iri(iri_ref, result.base_iri())
											.ok_or_else(|| {
												JsonLdError::InvalidBaseIri
													.at(entry_loc.object_value(JsonLdKeyword::Base))
											})?;
										result.set_base_iri(Some(resolved))
									}
								},
							}
						}
					}

					// 5.8) If context has a @vocab entry:
					// Initialize value to the value associated with the @vocab entry.
					if let Some(value) = context.vocab() {
						match value {
							JsonLdNullable::Null => {
								// If value is null, remove any vocabulary mapping from result.
								result.set_vocabulary(None);
							}
							JsonLdNullable::Some(value) => {
								// Otherwise, if value is an IRI or blank node identifier, the
								// vocabulary mapping of result is set to the result of IRI
								// expanding value using true for document relative. If it is not
								// an IRI, or a blank node identifier, an invalid vocab mapping
								// error has been detected and processing is aborted.
								// NOTE: The use of blank node identifiers to value for @vocab is
								// obsolete, and may be removed in a future version of JSON-LD.
								match result.expand_iri_with(
									JsonLdNullable::Some(value.into()),
									true,
									true,
									|w| env.warn(w),
								) {
									JsonLdTerm::Id(vocab) => {
										result.set_vocabulary(Some(JsonLdTerm::Id(vocab)))
									}
									_ => {
										return Err(JsonLdError::InvalidVocabMapping
											.at(entry_loc.object_value(JsonLdKeyword::Vocab)));
									}
								}
							}
						}
					}

					// 5.9) If context has a @language entry:
					if let Some(value) = context.language() {
						match value {
							JsonLdNullable::Null => {
								// 5.9.2) If value is null, remove any default language from result.
								result.set_default_language(None);
							}
							JsonLdNullable::Some(tag) => {
								result.set_default_language(Some(tag.to_owned()));
							}
						}
					}

					// 5.10) If context has a @direction entry:
					if let Some(value) = context.direction() {
						// 5.10.1) If processing mode is json-ld-1.0, an invalid context entry error
						// has been detected and processing is aborted.
						if self.options.processing_mode == JsonLdProcessingMode::JsonLd1_0 {
							return Err(JsonLdError::InvalidContextEntry
								.at(entry_loc.object_value(JsonLdKeyword::Direction)));
						}

						match value {
							JsonLdNullable::Null => {
								// 5.10.3) If value is null, remove any base direction from result.
								result.set_default_base_direction(None);
							}
							JsonLdNullable::Some(dir) => {
								result.set_default_base_direction(Some(dir));
							}
						}
					}

					// 5.12) Create a map `defined` to keep track of whether or not a term
					// has already been defined or is currently being defined during recursion.
					let mut result = TargetProcessedContext {
						value: &mut result,
						defined: DefinedTerms::new(),
					};

					let protected = context.protected().unwrap_or(false);

					// 5.13) For each key-value pair in context where key is not
					// @base, @direction, @import, @language, @propagate, @protected, @version,
					// or @vocab,
					// invoke the Create Term Definition algorithm passing result for
					// active context, context for local context, key, defined, base URL,
					// and the value of the @protected entry from context, if any, for protected.
					// (and the value of override protected)
					if context.type_().is_some() {
						self.define(
							env,
							&mut result,
							&context,
							JsonLdKeyOrKeywordRef::Keyword(JsonLdKeyword::Type),
							protected,
							entry_loc,
						)
						.await?
					}

					for (key, _binding) in context.bindings() {
						let binding_loc = if context.key_is_imported(key) {
							entry_loc.file(JsonLdSourceFileRef::original(import_url.as_deref()))
						} else {
							entry_loc
						};

						self.define(
							env,
							&mut result,
							&context,
							key.into(),
							protected,
							binding_loc,
						)
						.await?
					}
				}
			}
		}

		Ok(result)
	}
}

// /// Result of context processing functions.
// pub type ProcessingResult<'a, T, B> = Result<Processed<'a, T, B>, Error>;

// pub trait Process {
// 	/// Process the local context with specific options.
// 	#[allow(async_fn_in_trait)]
// 	async fn process_full<N, L, W>(
// 		&self,
// 		vocabulary: &mut N,
// 		active_context: &Context<N::Iri, N::BlankId>,
// 		loader: &L,
// 		base_url: Option<N::Iri>,
// 		options: Options,
// 		warnings: W,
// 	) -> Result<Processed<N::Iri, N::BlankId>, Error>
// 	where
// 		N: VocabularyMut,
// 		N::Iri: Clone + Eq + Hash,
// 		N::BlankId: Clone + PartialEq,
// 		L: Loader,
// 		W: WarningHandler<N>;

// 	/// Process the local context with specific options.
// 	#[allow(clippy::type_complexity)]
// 	#[allow(async_fn_in_trait)]
// 	async fn process_with<N, L>(
// 		&self,
// 		vocabulary: &mut N,
// 		active_context: &Context<N::Iri, N::BlankId>,
// 		loader: &L,
// 		base_url: Option<N::Iri>,
// 		options: Options,
// 	) -> Result<Processed<N::Iri, N::BlankId>, Error>
// 	where
// 		N: VocabularyMut,
// 		N::Iri: Clone + Eq + Hash,
// 		N::BlankId: Clone + PartialEq,
// 		L: Loader,
// 	{
// 		self.process_full(
// 			vocabulary,
// 			active_context,
// 			loader,
// 			base_url,
// 			options,
// 			warning::Print,
// 		)
// 		.await
// 	}

// 	/// Process the local context with the given initial active context with the default options:
// 	/// `is_remote` is `false`, `override_protected` is `false` and `propagate` is `true`.
// 	#[allow(async_fn_in_trait)]
// 	async fn process<N, L>(
// 		&self,
// 		vocabulary: &mut N,
// 		loader: &L,
// 		base_url: Option<N::Iri>,
// 	) -> Result<Processed<N::Iri, N::BlankId>, Error>
// 	where
// 		N: VocabularyMut,
// 		N::Iri: Clone + Eq + Hash,
// 		N::BlankId: Clone + PartialEq,
// 		L: Loader,
// 	{
// 		let active_context = Context::default();
// 		self.process_full(
// 			vocabulary,
// 			&active_context,
// 			loader,
// 			base_url,
// 			Options::default(),
// 			warning::Print,
// 		)
// 		.await
// 	}
// }