zjkmxy · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,12 @@
 Changelog
 =========
 
+Next (breaking)
++++++++++++++++
+* Replace the descriptor-based TLV model with dataclass models and ``tlv_encode``/``tlv_parse``.
+* Make the PIT-token-aware application API canonical at ``ndn.app`` and remove ``ndn.appv2``.
+* Remove the legacy application API, Name Tree Schema, dispatcher, segment fetcher, and cascade validator.
+
 0.4-1 (2023-08-21)
 ++++++++++++++++++
 * Update dependencies: drop cryptography.

diff --git a/docs/_static/schema-example1-policy.svg b/docs/_static/schema-example1-policy.svg
diff --git a/docs/_static/schema-example1-schema.svg b/docs/_static/schema-example1-schema.svg
diff --git a/docs/index.rst b/docs/index.rst
@@ -15,10 +15,8 @@ Table Of Contents
    src/readme
    src/installation
    src/app
-   src/appv2
    src/encoding/encoding
    src/security/security
-   src/schema/schema
    src/lvs/lvs
    src/misc
    src/examples/examples

diff --git a/docs/src/app.rst b/docs/src/app.rst
@@ -4,82 +4,23 @@
 Introduction
 ------------
 
-The :mod:`ndn.app` package contains the class :any:`NDNApp` ,
-which connects an NDN application and an NFD node.
-
-:any:`NDNApp` provides the functionalities similar to application Face in ndn-cxx, which include:
-
-+ Establish a connection to an NFD node.
-+ Express Interests and handle the Data coming back.
-+ Register and unregister a route with an Interest handling function.
-
-This package does not support PIT token.
-To use PIT token, consider using :mod:`ndn.appv2` package.
-
-.. _label-keyword-arguments:
-
-Keyword Arguments
------------------
-
-Some functions which create a Interest or Data packet accept a ``kwargs``,
-which can be used to support diversity in arguments provided to create a packet.
-
-MetaInfo
-~~~~~~~~
-
-These arguments are used to fill in the MetaInfo field of a Data packet.
-
-+ **meta_info** (:any:`MetaInfo`) - the MetaInfo field of Data.
-  All other related parameters will be ignored.
-+ **content_type** (*int*) - :any:`ContentType`. ``ContentType.BLOB`` by default.
-+ **freshness_period** (*int*) - FreshnessPeriod in milliseconds. ``None`` by default.
-+ **final_block_id** (:any:`BinaryStr`) - FinalBlockId. It should be an encoded :any:`Component`.
-  ``None`` by default.
-
-InterestParameters
-~~~~~~~~~~~~~~~~~~
-
-These arguments are used to fill in fields of an Interest packet.
-
-+ **interest_param** (:any:`InterestParam`) - a dataclass containing all parameters.
-  All other related parameters will be ignored.
-+ **can_be_prefix** (*bool*) - CanBePrefix. ``False`` by default.
-+ **must_be_fresh** (*bool*) - MustBeFresh. ``False`` by default.
-+ **nonce** (*int*) - Nonce. A random number will be generated by default.
-  To omit Nonce, please explicitly pass ``None`` to this argument.
-+ **lifetime** (*int*) - InterestLifetime in milliseconds. ``4000`` by default.
-
-  .. warning::
-     On Windows, a too small number may cause a memory failure of the NameTrie. Currently, ``>=10`` is safe.
-+ **hop_limit** (*int*) - HopLimit. ``None`` by default.
-+ **forwarding_hint** (*list[NonStrictName]*) - see :any:`InterestParam`.
-
-Signature
-~~~~~~~~~
-
-These arguments are used to decide how the Interest or Data packet is signed and by which Signer.
-Supported arguments are different with each Keychain.
-Only those supported by the default Keychain are listed here.
-If there is a conflict, the earlier an argument is listed the higher priority it has.
-
-.. note::
-  Only Interests with ApplicationParameters are signed.
-  ``b''`` can be used if that field is not needed by the application.
-
-+ **signer** (*Signer*) - the Signer used to sign this packet.
-  All other related parameters will be ignored. The Keychain will not be used.
-+ **no_signature** (*bool*) - not signed. Not recommended.
-+ **digest_sha256** (*bool*) - using SHA-256 digest to protect integrity only. ``False`` by default.
-+ **cert** (:any:`NonStrictName`) - using the speficied Certificate to sign this packet.
-  The Key name will be derived from the certificate name.
-+ **key** - using the specified Key to sign this packet.
-  Either a Key object or the :any:`NonStrictName` of a Key is acceptable.
-  KeyLocator will be set to the default Certificate name of this Key unless specified.
-+ **identity** - using the default Key of the specified Identity to sign this packet.
-  Either an Identity object or the :any:`NonStrictName` of an Identity is acceptable.
-  The default Identity will be used if all of the above arguments are omitted.
-+ **key_locator** (:any:`NonStrictName`) - using the specified KeyLocator Name regardless of which
-  Key is used.
+The :mod:`ndn.app` package contains :class:`NDNApp`, the canonical asyncio
+application API. It connects to an NDN forwarder and provides:
+
+* Interest expression and Data validation.
+* Interest handlers with PIT-token-aware reply callbacks.
+* Prefix registration and unregistration.
+* Signed NFD management commands.
+
+Consumer code calls :meth:`NDNApp.express` and receives ``(name, content,
+context)``. The context contains parsed metadata, signature pointers, the raw
+packet, and the deadline. Producer handlers receive ``(name, app_param, reply,
+context)`` and should send encoded Data through ``reply`` so PIT tokens are
+preserved.
+
+The application does not own a keychain. Use :meth:`NDNApp.default_keychain`
+when the default client configuration is desired, and pass an explicit signer
+to :meth:`NDNApp.express` or :meth:`NDNApp.make_data`.
 
 Reference
 ---------

diff --git a/docs/src/appv2.rst b/docs/src/appv2.rst
diff --git a/docs/src/encoding/encoding.rst b/docs/src/encoding/encoding.rst
@@ -4,66 +4,34 @@
 Introduction
 ------------
 
-The :mod:`ndn.encoding` package contains classes and functions
-that help to encode and decode NDN Name, NameComponent, Data and Interest.
+The :mod:`ndn.encoding` package encodes and decodes TLV values, NDN names,
+Interest packets, and Data packets. Its main parts are:
 
-There are three parts of this package:
-
-1. **TLV elements**: process TLV variables, Names and NameComponents.
-
-2. **TlvModel**: design a general way to describe a TLV format.
-   A TLV object can be described with a class derived from :any:`TlvModel`,
-   with members of type :any:`Field`.
-
-3. **NDN Packet Fotmat v0.3**: functions used to encode and parse
-   Interest and Data packets in
-   `NDN Packet Format Spec 0.3 <https://named-data.net/doc/NDN-packet-spec/current/>`_.
+1. TLV number, Name, and NameComponent primitives.
+2. Dataclass TLV models encoded with :func:`tlv_encode` and parsed with
+   :func:`tlv_parse`.
+3. NDN Packet Format 0.3 helpers for Interests and Data.
 
 .. _label-different-names:
 
 :any:`FormalName` and :any:`NonStrictName`
 ------------------------------------------
 
-To increase the flexibility, API in ``python-ndn`` accepts Name arguments in a wide range of formats,
-i.e. :any:`NonStrictName`, but returns an unified form, :any:`FormalName`.
-
-A Component is a NameComponent encoded in TLV format.
+APIs accept :any:`NonStrictName` values in several forms but return the
+canonical :any:`FormalName`, a list of encoded NameComponents.
 
 .. code-block:: python3
 
     component = b'\x08\x09component'
-
-A :any:`FormalName` is a list of encoded Components.
-
-.. code-block:: python3
-
     formal_name = [bytearray(b'\x08\x06formal'), b'\x08\x04name']
-
-A :any:`NonStrictName` is any of below:
-
-- A URI string.
-
-  .. code-block:: python3
-
-      casual_name_1 = "/non-strict/8=name"
-
-- A list or iterator of Components, in the form of either encoded TLV or URI string.
-
-  .. code-block:: python3
-
-      casual_name_2 = [bytearray(b'\x08\x0anon-strict'), 'name']
-      casual_name_3 = (f'{x}' for x in range(3))
-
-- An encoded Name of type :class:`bytes`, :class:`bytearray` or :class:`memoryview`.
-
-  .. code-block:: python3
-
-      casual_name_4 = b'\x07\x12\x08\x0anon-strict\x08\x04name'
+    casual_name_1 = '/non-strict/8=name'
+    casual_name_2 = [bytearray(b'\x08\x0anon-strict'), 'name']
+    casual_name_3 = b'\x07\x12\x08\x0anon-strict\x08\x04name'
 
 Customized TLV Models
 ---------------------
 
-See :doc:`../examples/tlv_model`
+See :doc:`../examples/tlv_model`.
 
 Reference
 ---------
@@ -72,5 +40,5 @@ Reference
 
     TLV Variables <tlv_var>
     Name and Component <name>
-    TLV Model <tlv_model>
+    Dataclass TLV Model <tlv_model>
     NDN Packet Format 0.3 <ndn_format_0_3>
diff --git a/docs/src/encoding/tlv_model.rst b/docs/src/encoding/tlv_model.rst
@@ -1,47 +1,19 @@
-TLV Model
-=========
+Dataclass TLV Model
+===================
 
 .. automodule:: ndn.encoding.tlv_model
 
-    .. autoexception:: DecodeError
-        :members:
+Public API
+----------
 
-    .. autoexception:: IncludeBaseError
-        :members:
+.. autofunction:: tlv_encode
 
-    .. autoclass:: IncludeBase
-        :members:
+.. autofunction:: tlv_parse
 
-    .. autoclass:: Field
-        :members: __get__, __set__, encode_into, encoded_length, get_value, parse_from, skipping_process
+.. autoclass:: NDNName
 
-    .. autoclass:: ProcedureArgument
-        :members: __get__, __set__, get_arg, set_arg
-        :exclude-members: encoded_length, encoded_into, parse_from
+.. autofunction:: tlv_get_arg
 
-    .. autoclass:: OffsetMarker
-        :exclude-members: encoded_length, encoded_into, parse_from, skipping_process
+.. autofunction:: tlv_set_arg
 
-    .. autoclass:: UintField
-        :exclude-members: encoded_length, encoded_into, parse_from
-
-    .. autoclass:: BoolField
-        :exclude-members: encoded_length, encoded_into, parse_from
-
-    .. autoclass:: NameField
-        :exclude-members: encoded_length, encoded_into, parse_from
-
-    .. autoclass:: BytesField
-        :exclude-members: encoded_length, encoded_into, parse_from
-
-    .. autoclass:: ModelField
-        :exclude-members: encoded_length, encoded_into, parse_from
-
-    .. autoclass:: RepeatedField
-        :exclude-members: encoded_length, encoded_into, parse_from
-
-    .. autoclass:: TlvModelMeta
-        :members:
-
-    .. autoclass:: TlvModel
-        :members: __eq__, asdict, encode, encoded_length, parse
+.. autoexception:: DecodeError